Tik-76.115 Monrovia Game Developer's Guide v5.0

Group: Hayabusa, Work: Monrovia, Responsible: Anssi Kanninen

Change Log

1. Introduction

1.1 Purpose of this document

The purpose of this document is to familiarize the reader with all the aspects of creating new games in the Monrovia environment. Useful issues from suggested software to using static and dynamic building blocks to create a playable gaming arena are covered.

1.2 Users

This document is intended for persons responsible for creating gaming arenas. In most cases they will have something to do with administrating the Monrovia server or most likely be administrators themselves so they have prior experience and a good understanding of the system and the environment it runs in. This is why everything is not explained to the most basic detail.

2. Software prerequisities

Creating everything needed for a playable arena does not require much software. Game definitions are stored in XML files and BMP files so you will only need a text editor and something to manipulate simple image files. GNU Emacs with XML-mode is preferred choice as an editor. It has also a hex-mode which may be handy for editing the color indices of the BMP file. Some simple pixel based drawing application which shows the palette in the right order is also needed. For example, GIMP is an excellent choice because the color index numbers of the palette can be listed and changed easily.

3. Creating a map

3.1 General game parameters

General game parameters are saved in the file gameparams.xml. It contains the default walk, player and ground parameters. These have to be changed quite rarely. It also contains the game commands, their parameters and possible command classes. Few of them are explained here as an example. These commands can be considered as some kind of standard commands included in every type of game.

The parameters for monrovia.server.platform.commands.Say:

say format: the format of the message displayed to the listening parties
say you format: the message format displayed to party issuing the command
command arg: -1 means a string command argument and 0 means no arguments, so for a say command this should be -1

The parameters for monrovia.game.commands.Look:

command arg: always 0 because we don't have any arguments for this command

3.2 Adding an arena

When adding a new arena the first thing is to add it to the arenas.xml file. This file contains the names of directories where the game data is saved. Each arena has its own directory. For example adding an arena called korso would require the following line to be added to arenas.xml:

<java.lang.String valueOf="korso"/>

3.3 Bitmap of the arena

The map image of the arena is saved in the bitmap file map.bmp. This is a 256 color BMP file which allows 256 different objects. It will end up looking very much like map with colored pixels each representing an object. A pixel's color value is mapped as an index into the map.xml file (see chapter 4.2) which lists the bitmaps for all static objects.

3.4 Adding portals

A portal is a "door" for moving from one arena to another. It is a special spot on the map that acts as a gateway between two arenas. Portals are added to the portals.xml file. Every portal has a name, implementing class, a list of points on the map the portal is going to be and the portals parameters. The coordinates for the portal are measured from the top left corner of the arena. For example having a portal five squares down from the top left corner would require the following to appear in portals.xml:

<ArrayOf-java.lang.Object length="1">
   <monrovia.tools.IntPoint
   mX="0"
   mY="5"/>
</ArrayOf-java.lang.Object>

The parameters for implementing class monrovia.server.platform.map.ArenaPort:

target arena: the arena where the player is going to be transported when entered to the portal
target point: the destination point on the target arena
message: the message the player sees when entering the new arena

4. Creating static map objects

4.1 Object bitmaps

The object bitmaps are in the raw palm bitmap format and 16x16 in size. To get a raw palm bitmap from a windows bmp file, first create a 2 color bmp file with size 16x16 and then use the bmp2bitmap script to convert it. For example to convert orc.bmp to orc.bin a command like this could be used: bmp2bitmap orc.bmp -write orc.bin

4.2 Adding the objects to the map

To add objects to your map you will need the map.xml file. This file acts as a link between the map and the objects. It has a list of object bitmaps without the .bin extension (e.g. tree.bin is listed as tree) looking like this:

<java.lang.String valueOf="tree"/>
<java.lang.String valueOf="mountain"/>
<java.lang.String valueOf="door"/>

One should be careful with the order of these objects as the pixel values of map.bmp are used as indexes of the objects based on this order.

5. Creating dynamic map objects

5.1 Object bitmaps

Every dynamic object has a bitmap associated with it. The format is the raw palm bitmap format and 16x16 in size, the same as for the static bitmaps.

5.2 Adding object descriptions

The file creatures.xml lists all the creatures on the arena. Every creature has a name, the implementing class and the object bitmap name (e.g. orc.bin) and also the number of creatures to create with these parameters so that the game designer can create many identical creatures easily. Adding new parameters to creatures is very much like adding portals or creating static map objects due to the nature of XML. The easiest way to add something is to see how it was done before and just copy it and modify the parameters to meet your current needs.

Currently possible implementing classes:

monrovia.game.creatures.ScaredCreature:
monrovia.game.creatures.NeutralCreature:
monrovia.game.creatures.AggressiveCreature:

In addition to these behaviour classes every creature has these possible parameters:

start point: the point the creature starts on the map, random if not specified
sayings: a list of messages the creature says at random intervals (keep these short)
special attacks: a list of special attack messages, that are displayed to the player while fighting the creature (keep these short)
special attack maxdam: maximum damage caused by a special attack by this creature
moving radius: the radius that constrains the creature's random movement
strength: affects the damage caused and the ability to prevent other creatures fleeing from combat
size: affects the damage caused and the ability to keep other creatures from fleeing from combat and also maximum hitpoints, negative effect on armor class
dexterity: positive effect on armor class, hit percent and the ability to flee from fights
constitution: increases maximum hitpoints
experience: the creature's level increases with experience, the level has a positive effect on all aspects of fighting
intelligence: reserved for future use
wisdom: reserved for future use
race: nice statistic, maybe used in future gameplay

6. Summary of the files

In this chapter you will find a simplified list of all the files involved in creating a new game.

7. Troubleshooting

Problem Solution
"Couldn't load <filepath>" message is displayed and the server does not start. This message is displayed if a needed file is missing or the syntax of some XML file is wrong. Filepath is the path to the file with the problem. Check that the file is in the correct place and in the correct format.
"pixel value : <x> in map is greater than tile amount: <y>" message is displayed and the server does not start The tile amount described in map.xml is too low for the pixel values in map.bmp. Since the pixel values are used as indexes into map.xml, there must be enough tiles for the largest pixel value.

8. Other documents

Like stated in the beginning of this document not everything is explained to the smallest detail. If something was left unclear or you wish to find out more you should try Administrator's Guide, Client Guide and Technical Specification.
Administrator's Guide deals with the aspect of managing the Monrovia server, from setting up the required environment to handling player issues by using the special administration tool.
Client Guide is all you need to be able to install the gaming software, connect to the Monrovia server and start playing the game.
Technical Specification is not as light reading as those two documents mentioned before. It has hardcore descriptions and definitions of everything from protocol details to user interface solutions.