RolePlayingDesign

<?plugin CreateToc with_toclink||=1 ?>

!!Actions and Objects Last updated: 2003/10/07

The whole Marauroa system is managed by two main entities, RPAction and RPObject !Actions To express the willing of a client to do something it must send the server a MessageC2SAction message.

An action is composed of several attributes, an attributed is similar to a variable that has a name and contains a value.

There are optional and mandatory attributes. If a mandatory attribute is not found, the message is skipped by the RPServerManager.

Mandatory Actions Attributes are action_id and type.

The action_id is used to identify the action when a resulting response comes in a perception

Optional Actions Attributes: (Read "Actions Explained" for more details.)

!Objects The containers of information of the whole Marauroa server are RPObjects. An object is composed of several attributes, an attribute is similar to a variable that has a name and contains a value and also it is composed of Slots. A Slot is a container or array of containers that the object has to host other objects inside it.

Mandatory Object Attributes: id

Optional Object Attributes: (Read "Objects Explained" for more details.)

!! Object Explained Last updated: 2004/04/27

Objects are the basic Marauroa data structure, and you should already be familiarized with it because you read the Actions and Object document.

Marauroa engine only enforce that objects has two attributes: - id - type

id is an unique identification for the Object and type is the type of the object aka class, so that you can share attributes for all the instances of the class.

Also engine give special treatment to two types of attributes: - Attributes that begin with ! are completely hidden for all the users but the owner of the object. - Attributes that begin with # are completely hidden for all the users.

NOTE: This document relates to an early specification of Gladiators and is no longer relevant as it refers to specification, but can help you to know how to make the basic steps to define a game.

So let's point the multiple objects that we are going to have in Marauroa and their attributes and slots. Most object share a few attributes. They are: - object_id - object_type - object_look - object_position

The object_id attribute define the unique identifier of the object in the world. The object_type define the type of object it is, for example: human. The object_look would point to the model used to represent this object. The object_position determine where the object is in the world using a X, Y basis Again, we could add the Z value, but it is totally fake, we calculate Z for adjusting character to terrain.

Object Avatar The avatar is the entity in Marauroa that represent our character and it is the way of handling everything in that world. This object must have also the next set of attributes: - object_name

Also add too the RP attributes that are still to be defined. The object_name is just the name of the character this object is representing. The object has the next slots: - left_hand - right_hand - backpack

Object Stone A stone is just a little rock used for testing get, release and exchange actions.

Object Torch A torch is a small piece of wood in form of stick that is used to light on the near area. This object must have the next set of attributes: - object_status

The object_status define if the torch is ON or OFF.

Object Chest A wooden box with a lock that can be open or closed and can contain items inside. This object must have the next set of attributes: - object_status - object_forkey

The object_status define if the chest is OPEN or CLOSED. The object_forkey define the identifier of the key that opens this lock. The object has the next slots: - container

Object Key A small piece of metal that is placed inside the lock to unlock it. This object must have the next set of attributes: - object_key

The object_key define the identifier of the key.

!!Object and Slots Last updated: 2003/11/28

As you know Objects can contain inside another object much like you have the keys inside your pocket. The goal of Slots is to provide a richer game play while reducing the number of object in the zone.

To have these objects inside, we need our hoster object to have slots to place them. One slot can only handle one single object.

For example a avatar can have: - left hand - right hand - backpack - left pocket - right pocket

and we can store objects on these slots.

!! Actions Explained Last updated: 2003/10/23

NOTE: This section relates to an early specification of Gladiators and is no longer relevant as it refers to specification, but can help you to know how to make the basic steps to define a game.

Arianne Game is based on several actions that are a MUST for the correct development of the game. Mainly these actions are:

- Talk - Move - Object handling

 - Get
 - Release
 - Use
 - Use with
 - Exchange

These actions have their own attributes so that they can be useful for the game itself. Let's see these attributes and what each action is intended to be for. As common attributes, every action has the type attribute that express the type of Action that it is, and the sourceid express the object that is casting the action, but this attribute is filled on server rather than in client.

Action Talk This action is intended to express what the character wants to say. As that it is sent from client to server. Action has this next set of attributes: - type - sourceid - talk_text

The talk_text attribute is for containing the text that send the client.

Action Move This action is intended to indicate the willing to move from one point to another point. Action has this set of attributes: - type - sourceid - move_to - move_speed

The move_to is a Position , in the system the Z is a fake, as there is no technology ready for using a huge world with multiple levels. The move_speed is also a meaning the increase of positions per turns. This action should take care of: - Collision detection - Path finding

Action Get This action is intended to indicate the action of taking one object from floor. Action has this set of attributes: - type - sourceid - get_objectid - get_toSlot

The get_objectid is the RPObject.ID of the object we want to get and the get_toSlot attribute is the Slot of the character that send the action where the object is placed. This action has several limitations: - You can't get players - The destination slot must be free

Action Release This action is the contrary of Get, and it is used to drop an object from a Slot. Action has this set of attributes: - type - sourceid - release_fromSlot - release_objectid

The release_fromSlot is the slot that contains the object pointed by release_objectid. The only limitation of this action is that of course the object MUST be there.

Action Use This action makes the object to perform the expected action from them. This action is a real good candidate for scripting. Action has this set of attributes: - type - sourceid - use_objectid

The use_objectid attribute point the object to use. By now we will only have one default Use, later we can add extra attributes to the action.

Action ~UseWith This action is closely related with Use action, the difference is that we use ObjectA with ObjectB so that the state of ObjectA is modified, ObjectB may be modified as well. Action has this set of attributes: - type - sourceid - usewith_objectidA - usewith_objectidB

The usewith_objectidA refers to the Object that is the center of the action and usewith_objectidB is the catalyzer of the action. For example a door and a key respectively.

Action Exchange This action is use to exchange an object between two characters. Action has this set of attributes: - type - sourceid - exchange_sourceSlot - exchange_destObjectid - exchange_destSlot

The exchange_sourceSlot is the slot of the source character that owns one of the objects and the exchange_destObjecid is the other object and exchange_destSlot is the slot where the other object is. The action MUST be executed by both peers on the same terms so they agree and the action is executed.

Action replies are placed inside Objects and sent to clients as perceptions, so please refer to the Action reply in "Objects Explained" document.

!! How Perceptions and Actions work Last updated: 2004/04/27

Actions are sent from client to server in order to make their character to do an action. In order for the client to know the result of the action Server need to send it to client. How?

On a first try, we used to send client back an action that was the result, but make code really hard because we had to update to different things, perceptions and actions, so the idea appeared intuitively: Why not join action reply and perceptions.

So the action reply is stored inside each object (that executed the action ) with a set of attributes that determine the action return status and the attributes. This way of working make a bit harder to RPManager but it simplify a lot the creation of new clients.

See Actions reply in Objects document to know exactly what is returned, but keep in mind that it depends of each particular game.

!! RPManager Last updated: 2003/11/23

The goal of RP Manager is to handle the whole RP game. This means mainly: - run RPActions from clients - manage RPWorld - control triggers for events - control AI

As you see this is a HUGE class that is complex. So the idea is to split this behavior into smaller subclasses.

RPManager provides a simple interface to the ~GameManager for using it: - addRPAction - addRPObject - removeRPObject - hasRPObject

addRPAction simply queues an action for that player to be executed on the next turn.

addRPObject, removeRPObject and hasRPObject is a interface to manage RPWorld.

The main outline of RPManager could be:

<verbatim> forever

 {
 Procced through every action in this turn
 Build Perception
 Remove timed out players

 Wait for Turn completion.
 Go to Next Turn
 }

</verbatim>

As this part of Marauroa is subject still to development, there are still not many details.

RPScheduler is the class that handles actions to be queued for each player. All the complexity of Action management should be handled here.

~RuleProcessor is a wrapper class for hide actions code. All the actions code MUST be here, this class also acts as a Action code loader, as some actions are not part of Marauroa, but scripts.

!! Delta perception Algorithm Last updated: 2004/04/27

The main idea behind the DPA is not to send ALL the objects to client, but only those that has been modified.

Imagine that we have 1000 objects, and only O1 and O505 are active objects that are modified each turn. Ok?

Traditional method:

- Get objects that our player should see ( 1000 objects ) - Send them to player ( 1000 objects ) - Next turn - Get objects that our player should see ( 1000 objects ) - Send them to player - Next turn ... I hope you see the problem..., we are sending again objects that never changed.

The delta perception algorithm:

- Get objects that our player should see ( 1000 objects ) - Reduce the list to the modified ones ( 1000 objects ) - Store also the objects that are not longer visible ( 0 objects ) - Send them to player ( 1000 objects ) - Next turn - Get objects that our player should see ( 1000 objects ) - Reduce the list to the modified ones ( 2 objects ) - Store also the objects that are not longer visible ( 0 objects ) - Send them to player ( 2 objects ) - Next turn ... The next step on delta perception algorithm is pretty clear: delta^2 The idea is to send only what changes of the objects that changed. That why you save even more bandwidth, making perceptions around 20% of the delta perception size.

The delta^2 algorithm is based on four containers:

- List of added objects - List of modified added attributes of objects - List of modified deleted attributes of objects - List of deleted objects An area really related to DPA is RPZone

In order to get the Delta perception algorithm to work correctly you have to play with several parameters:

- RP Turn Duration - Relation between TOTAL perception and DELTA perception - Know your game :) Well, as you should know, MPEG adds a full frame each X number of frames, so it can be used as synchronization in case the file get corrupted. The idea is that if you fail to continue decompressing data, you can always omit things until the next full frame and then when you synced. The idea here is the same, we send a perception on each turn and every X turns we send a full perception so that clients can synchronize, as UDP is not a secure transport and you can also have new clients joining.

So the point is to adjust turn duration and relation so that the maximum time a client is out of sync is around 20-30 seconds. Of course, depending of the type of game you may lower or increase this value.

To make perception works it is important to call the modify method on RPZone so this way objects modified are stored in the modified list. If you skip this part the perception system will only work in Total mode.

!! Zones and Worlds Last updated: 2003/11/28

Objects must be stored somewhere, and we use Zones now to store them. A zone is just a container of Objects.

In order to improve the modifiability of the Marauroa platform we have made RPZone to be an interface so that if you want you can implement it as you think it is more efficient.

The actual Marauroa RP Zone consists of several data structures: - a ~HashMap of - a List of RPObject - a Perception

The idea is to have already computed in the Zone the perception so saving LOTS of time that would be needed to generate it. All the data structures contain the same objects, but the hashmap is used to fast search of objects using its RPObject.ID, this is the most usual way for locating the object. List is used to improve the time required to build a total perception. And well, we used perception to pre-calculate the delta perception.

Actually the perception is the same for all the players on the Zone, on the future we could split the zone into several smaller areas each of them would have its own perception

In order to make perceptions work, you have to manually call modify method so that you notify the zone about changes in a character.

!! Action Reply in Objects Last updated: 2003/11/28

NOTE: This section relates to an early specification of Gladiators and is no longer relevant as it refers to specification, but can help you to know how to make the basic steps to define a game.

As you have read in How Perceptions and Actions works, each Object includes the attributes that are result of the action execution. So for each action we will have:

Action Talk The attributes added to the object are: - action_talk_text

The action_talk_text contains the text the character has been asked to say. This action is always one turn only, and can never fail.

Action Move The attributes added to the object are: - action_move_destination - action_move_speed - action_move_status

The action_move_destination is the place where the object wants to go when the action ends, and it is as before a Position denoted by , action_move_speed is the assigned speed for the character by the RP. The action_move_status denotes if the action is complete, incomplete or failed. This action is completed when position=destination and fail if destination is unreachable.

Action Get The attributes added to the object are: - action_get_status

The action_get_status denotes if the action is complete or failed This action is always one turn long.

Action Release The attributes added to the object are: - action_release_status

The action_release_status denotes if the action is complete or failed This action is always one turn long.

Action Use The attributes added to the object are: - action_use_status - (Specific attributes depending on the object)

The action_use_status denotes if the action is complete, incomplete or failed. Usually this action modify attributes of the RPObject instead of adding new attributes.

Action ~UseWith The attributes added to the object are: - action_usewith_status - (Specific attributes depending on the object)

The action_usewith_status denotes if the action is complete, incomplete or failed. Usually this action modify attributes of the RPObject instead of adding new attributes.

Action Exchange The attributes added to the object are: - action_exchange_status - action_exchange_timeout

The action_exchange_status denotes if the action is complete, incomplete or failed. This action last several turns until both peers accept or the timeout elapses.

On every object that executed an action you will have a status_= that explains what happened with the action.

!! Attributes Last updated: 2003/12/22

Attributes are the containers of information in Marauroa. They are designed to contains strings, because they are the most flexible.

We have also added support for List of Strings. They are encoded as: <verbatim> name=[value|...|value] </verbatim>

Try to keep the names as short as possible.

!! Classes of Objects Explained Last updated: 2004/07/13

Classes of Objects are the basic way of structuring Marauroa data structures.

A class defines types of the attributes and its visibility and gives it an internal code that is used to speed up searchs and save bandwidth. You can base a class on another, this feature is known as inheritance.

The data types available are: - Strings - Short strings ( up to 255 bytes ) - Integers ( 4 bytes ) - Shorts ( 2 bytes ) - Byte ( 1 byte ) - Flag ( it is a binary attribute )

Attributes can also be visible if clients see them when they change, or invisible if clients can't see them.