Tik-76.115 Functional Specification, v5.0

Group: Hayabusa, Work: Monrovia, Responsible: Ilpo Nyyssönen

Last modified: Sun Apr 8 09:24:01 EEST 2001 - Ilpo Nyyssönen

Change Log

Table of Contents

  1. Introduction
  2. General
  3. Data
  4. Operations
  5. External Connections
  6. Other Properties
  7. Design Restrictions
  8. Further Development Ideas

1. Introduction

1.1 Purpose and Coverage of This Document

This document describes the functional behaviour of the Monrovia game platform. It should cover the whole system including the game.

1.2 Product

Monrovia is a multi-player, turn based game platform for Palm clients. The purpose of it is to show whether it is possible to do this kind of system.

As it is difficult to test, demonstrate or even design just a platform, a MUD-like game is also specified.

1.3 Definitions, Terms and Abbreviations

A handheld computer that is described more in chapter 7.2. See also <URL: http://www.palm.com/>.
The wide-area-networking protocol suite that makes the Internet work. [DICT: TCP/IP]
User Datagram Protocol. It is simple but unreliable protocol that provides datagram services. It neither guarantees delivery nor does require a connection. [DICT: User Datagram Protocol]
Multi-User Dungeon. It is a class of virtual reality experiments accessible via the Internet. These are real-time chat forums with structure; they have multiple 'locations' like an adventure game, and may include combat, traps, puzzles, magic, a simple economic system and the capability for characters to build more structure onto the database that represents the existing world. [DICT: MUD]

1.4 References

[DICT: keyword]
Some of the definitions were taken from dictionaries in DICT (<URL: http://www.dict.org/>) with the given keyword. (2000-11-01).

1.5 About This Document

This first chapter describes the purpose of this document, something general about the product and used terms.

Chapter 2. describes the general functionality of the system, the hardware in it, the users and the dependencies and restrictions.

Chapter 3. describes the data that the system contains and the data flow.

Chapter 4. describes the operations of the system. Operations and effects caused by the operation and input are described for each operation.

Chapter 5. describes the external connections to hardware devices, to software and through communication.

Chapter 6. describes the non-functional properties like performance, response times, usability and maintainability.

2. General

2.1 Environment

The system has two parts. The server contains the main functionality and the Palms are mainly an user interface to the system.

2.2 Operation

In the game a player has a character whose skills he/she tries to improve. A character will receive more strength and skills when he/she manages to do something which is considered to be worth experience, i.e. defeating other players or computer characters. Computer characters can be orcs, barbarians, elves, giraffes, cows or what ever is thought to be rational in this game. The commands and operations are quite simple and don't usually require much thinking.

The server has a loop where it processes the commands that it has received from the clients and then sends updates to the clients about the situation. A client either does or does not do something during a turn.

2.3 Users

The users of the system are the players with their Palms. Additionally there is the administrator that takes care of the server.

The players can be almost anyone. They should know something about Palms and something about computer games. The player can be almost anywhere when playing the game.

2.4 Restrictions

The biggest restriction from the software side is Java which must be used as the programming language.

On the hardware side the Palm handheld brings many limitations especially to the user interface. Also the Java that is used there is a subset of the Java used in the server side.

2.5 Assumptions and Requirements

Network connection can be slow and unreliable.

The resources of the server are big.

3. Data

3.1 Introduction

The most important data structures in Monrovia are the map-related entities, player information and system log. The map structure contains all the objects which the user can see in the game screen. There is a character in the map for each player. The log can be used to get information what has happened in the game.

We need to be able to load the game data from some kind of text files to be able to create those as the game data editor does not have such a high priority in this project. The interface used in loading and saving data should be abstract so that the method can be changed easily. The method that is implemented first, is to use some kind of XML file.

Here are listed the basic information structures for the game.

3.1.1 Map

Map contains most of the data in the system. The server updates it according to the commands from the clients and the commands from the computer handled characters. The server needs to be able to process the map and to get the up to date status for the client quickly. The map is a dynamic data structure that contains map objects. The map can be divided so that only parts of the map need to be loaded. Map Area

This is a divided part of the map. An area is always loaded and saved as an entity. The map is stored in memory as a fixed size two dimensional array, whose size is defined in the game data. Map Object

A map object is something in the map. There are three types of these: Ground, static and dynamic objects. The static and dynamic objects are stored in the ground object during the game. The static and dynamic objects have some common properties:

Static Map Object

This might be referred also as a azoic object. Static map object does not move or change. It can be for example a tree or a mountain.

Dynamic Map Object

This might be referred also as a character. Dynamic Map Object can move and change. It can be for example a player or a computer character. A dynamic object knows what to do after each round.

Ground Map Object

This is the object that contains the others. It can define what kind of ground this square has. For example a swamp could slowly kill the player that stays there. A portal is an example of a special type of ground. It is used for moving from area to another.

3.1.2 Player

Here are some structures that are used to describe the player. The sizes for those fields are not absolutely necessary, because the dynamic nature of Java. There might be a need to store those somewhere or to transfer over the network so the maximum sizes ease the implementations of those. Personal Information

Personal information contains the data used in authentication and user identification. Every user has some unique information about themselves so that billing and logging will be possible. Personal information is contained in the following structure:

string8 charsUnique user ID
string16 charsUser password
string32 charsReal name of the user
numberintegerIP Address or other network identification information
string16 charsName of the character, which the user plays Player Character Information

The data structure enables having multiple characters per player. The character has game status information, for example hit points, items carried, score and so on. This somehow linked to the character used in the map for this character.

string16 charsUnique name of the Character
numberintegerHit points
Array8 integersInventory of carried items
numberintegerID of the picture that is displayed for this character
numberintegerID of the character

3.1.3 Hi-score list

The high score list has a great importance because it makes the playing much more interesting. The score list has both the Player and the character information. The score list could be shown with some kind of popup menu when starting or stopping the game. Alternatively it could be located somewhere in the game.

string16 charsUser ID
string16 charsName of the Character
stringvariableCharacter status or other additional information

3.1.4 Game log

The most important game actions are logged. The log can be used as a base for billing and network traffic analyzing.

string16 charsUser ID
numbertimeTime stamp
numberintegerAction code
stringvariableAction description

3.2 Usage Intensity

The game will be played by 10 players simultaneously. Each of them can cause one playing action per second, one action per 2 seconds being the average. The system is running 24 hours a day.

3.3 Capacity requirements

The system must be able to save the most important log file entries for two months. After that they can be stored in CD-ROM or other removable medium. The Palm client must be able to handle all the map objects in 10 previously loaded map pieces. This requirement may vary depending on the memory space of a particular Palm device version.

4. Operations

4.1 General

The game is supposed to be played on a portable Palm computer. The screen in a Palm computer is rather small and it is rather difficult to write words with it. Therefore several limitations to the user interface had to be done. The screen could look like in the following picture.

Palm client picture

The screen is divided into three boxes. In the first box is displayed the visible area of the map which is 5x5. The player is positioned in the center of that area. In the second box are printed the available commands. The commands change depending on the square. It is meant to be so that the commands can be touched by Palm's pen. When a command is chosen, the command box is cleared and objects, which depend on the square, too, are written to the command box. The third box is used to display messages and to print the command line. The Palm has few buttons and they are used to make the game easier to play. One of the buttons is used to actually execute the commands. The language of the game is English.

4.2 Servers Operations

4.2.1 Startup


The server is started.


No input needed.

Processing, printing information and malfunction

If the startup succeeds, the game starts running and the server listens for connections from the port defined in configuration file. If the startup fails, an error message is printed and the server exits. The startup includes loading the game data and initializing the data structures needed to run the game.

4.2.2 Add Player


New player is added to the server.


Name of the player, password, name of the creature, starting arena and optionally starting point and creature parameters. This can be input by the administrator via admin tool or in future version directly by user from the web.

Processing, printing information and malfunction

If there is erroneous data, an error message is printed and the player is not added. Otherwise the player is added to the server and the player can connect with a Palm and start playing.

4.2.3 Remove Player


A player is removed from the server.


Name of the player, input by the administrator to the admin tool.

Processing, printing information and malfunction

Error message is printed, if the player does not exist. The player is kicked from the game, if she or he is playing when removed. After that the data structure of the player is removed.

4.2.3 Shutdown


The server is stopped.


The server is signaled the shutdown.

Processing, printing information and malfunction

If the process is just killed, the system just disappears, otherwise the client connections are shutdown and then the game is stopped and the needed savings are done.

4.3 Game Operations

4.3.1 User starts a new session


The user continues playing with his character.


The user starts the Monrovia program on his computer and then enters the IP address and port of the server, a username and password.

Processing, printing information and malfunction

The users inputs are sent to the server and the server processes them. If the username and password are correct then the server starts sending information, which is needed to play the game, to the client and marks the player as logged in. If the player in the previous session went "link dead", he will continue from the exact place where he last was. If the username or password is incorrect, then the server sends an error message to the client and the user must enter the username and password again.

4.3.2 The user quits the game


The user has played the game for a while and wants at some point to stop playing.


The user chooses "Disconnect" from the client menu.

Processing, printing information and malfunction

The client sends a quit-signal to the server. The server writes the necessary information to disk, logs the user off and sends a "successfully logged off" message to the client. The user is displayed a logged off screen and the game ends.

4.3.4 Connection is lost


The player has logged in, but at some point the server stops receiving packets from the client.


No input needed.

Processing, printing information and malfunction

The server time-outs, marks the character as "link dead" and writes the necessary information to disk. No information is sent to the client.

4.3.5 The player wants to start a fight


The player is playing the game and at some point wants to attack a computer character or another player.


The character tries to walk to the map tile that already has the enemy.

Processing, printing information and malfunction

If the attack is allowed in the current game situation, the server starts processing a fight between the player and the attacked character and sends messages to the client, which displays them on the screen. The fight stops, when one character dies, both characters die or one character leaves the square. Attacking other characters is possible in all squares.

4.3.5 The player moves


The player is playing the game and at some point wants to move his character to another square.


The player types the direction buttons.

Processing, printing information and malfunction

If the movement is impossible, the server sends an illegal movement message, which is dependent on the square where the player at the moment is, and the message is displayed on the client's screen. If the movement is possible, the server moves the character on the map and informs the client. The client then redraws the map, so that the new square is in the center and prints the commands, which are possible in that square to the command box. A message about the movement is also displayed on the screen.

4.3.6 Other game operations

There are a lot of possible operations that can be done in the game. Some of the most important commands will be listed here.

Say something to all the characters that exist in the screen.

4.3.7 Other client operations

Other operations which don't depend on the particular game, will be listed in the pull-down menu. Here are listed a few of them.

Close the network connection to the server and then reconnect or quit the game.
Prints some information of the application.

5. External Connections

5.1 Hardware Connections

The system does not support any external devices such as printers.

5.2 Software Connections

There is a possibility to use a database to store game data and user data. If a database will be used, it will be the latest stable version of PostgreSQL and it will be connected through JDBC (Java Database Connectivity).

5.3 Communication Connections

The system uses a TCP/IP network to communicate between the server and the Palms. The system uses its own protocol that uses both TCP and UDP. The TCP part is used to transfer the login information and such. The UDP part is used to transfer the game data.

6. Other Properties

6.1 Performance and Response Times

Response times can be divided into two separate situations, logging into the system or changing an arena (after authentication) and game play itself. The former may take a while (loading map symbols) but the latter must be smooth and responsive. The server has no performance issues as its resources are considered large and expandable.

6.2 Usability, Recovery, Security and Protections

Usability as mentioned earlier shall be easy enough that a person with little computer and gaming experience can learn the game with little or no effort. One recovery situation will be taken into account, a lost connection. It will be addressed as described in 4.3.4. Securtity will not be taken into account although it may be worth mentioning that one might quite easily implement security measures such as MD5 and EKE to the protocol layer later.

6.3 Maintainability

In theory the server could maintain its users and itself by itself. Practice will show how wrong this claim is.

6.4 Portability

As all the programming is done in Java which supposedly is platform independant, porting should not be impossible. The goals of the project however do not require any portability.

6.5 Operability

Operability is minimal as the server is running 24h.

7. Design Restrictions

7.1 Standards

Programming language is Java. See Software Restrictions later.

7.2 Hardware Restrictions

The server can be run on almost any modern computer. It needs to be able to run J2SE.

The clients need to be Palm handhelds that are able to run J2ME. The following hardware limitations apply on the PalmOS operating system and the Palm devices:

7.3 Software Restrictions

The server needs a Java Virtual Machine that supports Java 2 SDK Standard Edition version 1.3. Preferred operating system is Linux.

The client must have a Java Virtual machine like Sun's KVM running. The virtual machine has to be able to run J2ME code.

7.4 Other Restrictions

The network connection between the Palm and the server can be slow and unreliable.

8. Further Development Ideas

All the information in the server that is now kept in memory could be stored in a database.

Map editor would make map creation easier.

Character editor would make new computer character creation easier.

Player account administration program would ease player administration.

If security somehow becomes an issue security enhancements can be implemented to the protocol.

Porting to other platforms.