Last modified: Sun Apr 8 09:24:01 EEST 2001 - Ilpo Nyyssönen
This document describes the functional behaviour of the Monrovia game platform. It should cover the whole system including the game.
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.
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.
The system has two parts. The server contains the main functionality and the Palms are mainly an user interface to the system.
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.
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.
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.
Network connection can be slow and unreliable.
The resources of the server are big.
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.
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.
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.
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:
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.
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.
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.
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 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:
| Datatype | Size | Description |
|---|---|---|
| string | 8 chars | Unique user ID |
| string | 16 chars | User password |
| string | 32 chars | Real name of the user |
| number | integer | IP Address or other network identification information |
| string | 16 chars | Name of the character, which the user plays |
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.
| Datatype | Size | Description |
|---|---|---|
| string | 16 chars | Unique name of the Character |
| number | integer | Score |
| number | integer | Hit points |
| Array | 8 integers | Inventory of carried items |
| number | integer | ID of the picture that is displayed for this character |
| number | integer | ID of the character |
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.
| Datatype | Size | Description |
|---|---|---|
| string | 16 chars | User ID |
| string | 16 chars | Name of the Character |
| number | integer | Score |
| string | variable | Character status or other additional information |
The most important game actions are logged. The log can be used as a base for billing and network traffic analyzing.
| Datatype | Size | Description |
|---|---|---|
| string | 16 chars | User ID |
| number | time | Time stamp |
| number | integer | Action code |
| string | variable | Action description |
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.
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.
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.
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.
The server is started.
No input needed.
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.
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.
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.
A player is removed from the server.
Name of the player, input by the administrator to the admin tool.
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.
The server is stopped.
The server is signaled the shutdown.
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.
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.
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.
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.
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.
The player has logged in, but at some point the server stops receiving packets from the client.
No input needed.
The server time-outs, marks the character as "link dead" and writes the necessary information to disk. No information is sent to the client.
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.
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.
The player is playing the game and at some point wants to move his character to another square.
The player types the direction buttons.
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.
There are a lot of possible operations that can be done in the game. Some of the most important commands will be listed here.
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.
The system does not support any external devices such as printers.
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).
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.
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.
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.
In theory the server could maintain its users and itself by itself. Practice will show how wrong this claim is.
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.
Operability is minimal as the server is running 24h.
Programming language is Java. See Software Restrictions later.
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:
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.
The network connection between the Palm and the server can be slow and unreliable.
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.