RolePlayingDesign

• General Information
  • Overview
  • What is Marauroa?
  • Features
  • Glossary
  • Differences
  • History
  • New in Marauroa 3.8
  • New in Marauroa 3.9
• Using Marauroa
  • Building
  • Initial Steps
  • Tutorial
  • Core API
  • Adventure Games Concepts
  • Database Access
  • server.ini
  • Testserver
• Internals
  • Network Design
  • Role Playing Design
  • Database Design
  • Database Access
  • Eclipse
  • Roadmap
  • JUnit

This is possibly the most complex part of all the middleware that makes up Arianne.
Role Playing Design is the determining factor on how easy is to create a new game for Arianne. We had to choose easing the creation of turn time limited based games. Arianne will work better with this kind of games (also known as realtime games).

Role Playing Design tries to be generic and game agnostic (independant of the game being made). The very basic idea behind RPManager is:

  forever
    {
    Execute Actions
    Send Perceptions
    Wait for next turn
    }

To achieve this we use several classes:

• RPManager is coded in Marauroa and doesn't need to be modified.
• IRPRuleProcessor is the interface that you need to modify in order to personalize the actions that your game will execute.
• RPWorld is the class that you need to extend inorder to implement the onInit and onFinish methods which personalize what happens when you initialise the server and what happens when you close the server.
• IRPZone is an interface that you could implement if you wanted to achive the highest personalization possible of the engine, however, I would use MarauroaRPZone instead as that uses our great Delta² feature.

RPManager

The goal of the RP Manager is to handle the RP of the game. This means:

• run RPActions from clients
• manage RPWorld
• control triggers for events
• control AI

This is a HUGE task that is very complex. Hence we split this behavior into smaller subclasses.

RPManager exposes a simple interface to the GameManager:

• addRPAction
  This function queues an action for a particular player to be executed on the next turn.
• getRPObject
  This is an interface to manage RPWorld to ease the aquisition of the RPObject when exiting the game.
• onInit Player
• onExit Player
  These are callback functions that are used by GameManager to notify that a player has entered or exited the game.
• transferContent
  is a callback function that is called by RPRuleProcessor to stream content to players.

The main flow of RPManager is:

forever
  {
  Procced through every action in this turn
    {
    rpRuleProcessor executes action
    }

  Build Perception
  Remove timed out players

  Wait for Turn completion.
  Go to Next Turn
  }

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

RPRuleProcessor is a wrapper class for actions code and initialization and exit code.
All the actions code MUST be here.
By implementing RPRuleProcessor you personalize Marauroa to the game you want to make. However, keep in mind that you are limited to a realtime style game.

Objects and Actions

The whole Marauroa system is managed by two main entities, RPAction and RPObject. There are also several helper classes like Attributes, RPSlot and RPClass

Attributes

Attributes is a collection of pairs of values in the form name-value. We can store almost any basic type in a Attribute object:

• strings
• integer
• floats
• boolean

We can't store structures in the attribute, but you can convert groups of data to a string and store it as a string. Marauroa provides helper methods for this.

Objects

All information in the Marauroa server is contained in RPObjects. An object is composed of several attributes (an attribute is similar to a variable in that it has a name and contains a value) and Slots. A Slot is a container or array of containers belonging to an object, and are used to host (store) other objects inside them.

Mandatory Object Attributes: id, type and zoneid

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

An id is only unique inside the zone which contains that object.

NOTE: The engine provided two special types of attributes: - Attributes that begin with ! are completely hidden from all other users except the owner of the object. - Attributes that begin with # are completely hidden for all users.

Classes of Objects Explained

Classes of Objects are the basic way of structuring Marauroa data structures. The type of an attribute of a given object must be equal to a RPClass name of the type class you wish to use.

The class defines the type of the attribute, its visibility and assigns 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 (a new class is create from a class that already exists and takes all the original classes methods and data and extends it).

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 be visible which means clients see them when they change, or invisible if clients can't see them.

Slots

Objects can reside inside other objects 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 objects inside, we need our hoster object to have slots to place them in. One slot can only handle one single object.

For example an avatar can have:

• left hand
• right hand
• backpack
• left pocket
• right pocket

and we can store objects in each of these slots.

Once an object has been stored inside an objects slot, the only way of accessing the stored object is through the object that contains our stored object.

As attributes, slots have two special types:

• Slots names that start with ! are only sent to owner player. (Hence only seen by the owner)
• Slots names that start with # are not sent to players. (Invisible to all)

Actions

To express the willingness of a client to do something it must send the server a MessageC2SAction message.

An action is composed of several attributes. (an attribute is similar to a variable in that it 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 Action Attributes are action_id and type.

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

Perceptions

The basic structure for sending world updates to clients is called perceptions.

There are two types of perception:

• Sync perceptions: these are used to synchronize clients with the server world representation. This is the only valid way of knowing world's status.
• Delta perception: this is used to send only the changes to the world since the last perception.

Our actual Perception system is called Delta². It is heavily attached to the Marauroa core, so I recommend you to use it :)

How Perceptions and Actions work

Actions are sent from the client to the server in order to make the character perform an action. In order for the client to know the result of the action the Server needs to send a reply to the client. How will this be done?

In a first attempt, we send clients back an action that was the result of their action. However, this made the code really hard because we had to update two different things, perceptions and actions. Instead the solution appears 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 doing replies makes it a bit harder on RPManager but it simplifies the creation of new clients a lot.

See Actions reply in the Objects documentation to know exactly what is returned. However, keep in mind that the return result depends of each particular game.

Delta² perception Algorithm

The idea behind the DPA is to avoid sending ALL the objects to a client each time, but only those that have been modified.

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

The 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 objects that haven't changed each turn.

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 of the delta perception algorithm is pretty clear: delta² The idea is to send only what changes of the objects that changed. This way we save even more bandwidth, making perceptions around 20% of the original delta perception size.

The delta² 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 very related to DPA is RPZone (see lower in this doc)

As you should know, an MPEG video adds a full frame each X number of frames, so it can be used as synchronization in case the file gets corrupted. The idea is that if you fail to continue decompressing data, you can always omit things until the next full frame and then you get synced. The idea here is similar, if we fail to synchronize with server we send it an Out of Sync Message so that server will send a sync perception so that the clients can synchronize. Remember, UDP is not a secure transport.

To make perceptions work, it is important to call the modify method in RPZone, so this way objects modified are stored in the modified list.

Zones and Worlds

Worlds in Marauroa can be so big, so huge, that we need to split them in to several pieces. Each of these pieces are what we call an RPZone.

So our world is made of several RPZones that are independent of each other. To move from one RPZone to another RPZone you have to code the correct behaviour in RPRuleProcessor. Just look at any of our coded examples.

RPWorld

As we have already said, RPWorld stores several RPZones that are independent of each other.
RPWorld provides onInit and onFinish methods that are called on server initialisation and server finalization to define what to do with the world on these events. There is no default behaviour and you need to extend this class to redefine the behaviour.

Also it provides methods for adding and getting new RPZones:

• addRPZone
• getRPZone, which can be used with either RPZone.ID or RPObject.ID

Finally it also contains methods for managing RPObjects as:

• addRPObject, that need that our RPObject contains a valid RPZone.ID inside its RPObject.ID
• getRPObject
• modifyRPObject
• changeZone that moves one object from the old zone to the new zone and adds a proper valid id.

At last, RPWorld also contains a method called nextTurn that is called by RPManager to move from one turn to the next turn. It resets the delta² data.

RPZone

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

Each RPZone must have a unique name.

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 require.

But in most cases, if you think the Delta² system is fine and matches your games style, you can use MarauroaRPZone that is our reference implementation of Delta² algorithm.

The actual Marauroa RPZone consists of several data structures:

• a HashMap of RPObject.ID to RPObject
• a List of RPObject
• a Perception

The idea is to have already computed, in the Zone, the perception hence saving LOTS of time that would normally be needed to generate it. All the data structures contain the same objects, but the hashmap is used to do a fast search of objects using the RPObject.ID. This is the most common way for locating an object with a known ID. List is used to improve the time required to build a total perception. Perception is used to pre-calculate the delta perception (i.e. to find the changes between the current state of the zone and the previous state send to the client last turn)

The perception is the same for all the players in the Zone.

In order to make perceptions work, you have to manually call the modify method so that you notify the zone about changes in a character or object. {{#breadcrumbs: Marauroa | Internals | Role Playing Design }}