Marauroa Core API

Marauroa exposed a very simpled and reduce API in order for you to develop your own games.

!!!Content The main entities you should know about are:

• Attributes
• RPAction
• RPObject
• RPSlot
• RPClass

If you plan to use Java only also you should know:

• IRPZone interface
• IRPRuleProcessor interface

Or if you prefer Python for developing the rules:

• ~PythonZone
• PythonRP

!! Attributes Attributes are a list of pairs name, value that store information in Arianne. The methods exposed by Attributes class are: Sets the value of an attribute

• void put(String name, String value)
• void put(String name, int value)

Add quantity to the value of an attribute that MUST exists

• void add(String name, int quantity)

Returns the value of an attribute

• String get(String name)
• int get(String name)

Removes an entry of the list of attributes

• void remove(String name)

Returns True if an attribute exists

• boolean has(String name)

Each attribute has its type that is define in a RPClass. An attributes is an instance of a RPClass. There are two special entries at attributes:

• type that define the name of the RPClass the object belong to.
• id that define an unique

_Example_: %%% <verbatim>

 Attributes test=new Attributes();
 test.put("name","Test attribute");
 test.put("hp",100);

 if(test.has("hp"))
   {
   test.add("hp",10);
   }

 test.remove("name");

</verbatim>

!! RPClass This class is a key concept at Arianne. An RPClass is much like a Java Class but for Arianne RPObjects: it defines the type ( string, int, boolean, ... ) and the visibility ( hidden attribute or visible attribute ) of the attributes that make an object. RPClass has five different parts: Type Data definition:

• String a string of up to 2^32 bytes
• Short String a string of 255 bytes
• Integer a 32 bits integer
• Short a 16 bits integer
• Byte a 8 bits integer
• Flag a binary flag.

Visibility Data definition:

• Visible if the attribute can be seen by clients.
• Hidden if the attribute is not visible by clients.

Creation of the RPClass:

• void add(String name, byte type)
• void add(String name, byte type, byte visibility)
• void isA(String parent)
• void isA(RPClass parent)

These methods adds attributes to the RPClass and set the parent of this class. Of course a class can have no parent.

Query:

• String getName()
• byte getType(String name)
• byte getVisibility(String name)
• boolean hasAttribute(String name)
• boolean subclassOf(String parentclass)

Once the class is filled with data, you can querey using these methods to get the class name of the class, the the type of an attribute, determine if an attribute exists and to know if that RPClass is a subclass of another.

Class wide query:

• boolean hasRPClass(String name)
• RPClass getRPClass(String name)

You can query the system classes using these methods, it is not a good idea to modify them once you are running. The class definitions are send to client on connect, if you change class definitions on the middle of a game it is prone that you will crash your clients.

When writting a class definition you can skip id and type attributes as they are automatically determined by RPClass.

_Example_: %%% <verbatim>

 RPClass objclass=new RPClass("position");
 objclass.add("x",RPClass.BYTE);
 objclass.add("y",RPClass.BYTE);

 objclass=RPClass("player");
 objclass.isA("position");
 objclass.add("name",RPClass.SHORT_STRING);
 objclass.add("dir",RPClass.SHORT_STRING);
 objclass.add("score",RPClass.INT);
 objclass.add("super",RPClass.BYTE);
 objclass.add("!vdir",RPClass.STRING,RPClass.HIDDEN);
 objclass.add("!hdir",RPClass.STRING,RPClass.HIDDEN);
 objclass.add("?kill",RPClass.FLAG);

</verbatim>

Each time you create a new RPClass and as long as you give it a name ( ie: player, position, ... ) it will be added to the system list of classes. Notice on the example the HIDDEN attribute, by default an attribute is visible. You can choose not to use RPClasses on your application but the performance penalty will be big both on bandwidth and CPU usage.

!! RPAction It is a object to represent actions that player wants to do. It is up to your game about how to define the content ( you should also define a RPClass for these ).

!! RPObject and RPSlot An RPObject is the containter of data in Arianne. An RPObject _isa_ Attributes with a list of RPSlots. Think about RPSlots as backpacks, pockets, boxes, ... The new methods are:

• void addSlot(RPSlot slot)
• RPSlot getSlot(String name)
• void removeSlot(String name)
• boolean hasSlot(String name)
• Iterator slotIterator()

These methods adds a slot to the object, retrieve it, remove it and test if the slot exists. Finally the slot iterator is used to visit all the slots in the object.

• RPObject.ID getID()

This is a helper method to get the ID of the object.

RPSlot has also a very simple API:

• void add(RPObject object)
• RPObject get(RPObject.ID id)
• boolean has(RPObject.ID id)
• RPObject remove(RPObject.ID id)
• void clear()

The clear removes all the object of the slot.

• Iterator iterator()

It is used to visit all the objects of the slot.

<verbatim>

 RPObject object=new RPObject(RPClass.getRPClass("player"));
 object.put("name","example");
 object.put("score",0);

 RPSlot slot=new RPSlot("backpack");
 RPObject coin=new RPObject();
 coin.put("type","coin");
 slot.add(coin);
 object.addSlot(slot);

</verbatim>

Now the complex part, where all the nuts are: IRPZone and IRPRuleProcessor interfaces

!! IRPZone This is the class that handle the world content and the perceptions. It would be wise to forget about it, or extend MarauroaRPZone instead as it is a really complex and bug prone class. The methods are: <verbatim>

 /** This method is called when the zone is created to popullate it */
 public void onInit() throws Exception;
 /** This method is called when the server finish to save the content of the zone */
 public void onFinish() throws Exception;

 /** This method adds an object to the Zone */
 public void add(RPObject object) throws RPObjectInvalidException;
 /** This method tag an object of the Zone as modified */
 public void modify(RPObject object) throws RPObjectInvalidException;
 /** This method removed an object of the Zone and return it.*/
 public RPObject remove(RPObject.ID id) throws RPObjectNotFoundException;
 /** This method returns an object of the Zone */
 public RPObject get(RPObject.ID id) throws RPObjectNotFoundException;
 /** This method returns true if the object exists in the Zone */
 public boolean has(RPObject.ID id);

 /** This method create a new RPObject with a valid id */
 public RPObject create();

 /** Iterates over the elements of the zone */
 public Iterator iterator();
 /** Returns the number of elements of the zone */
 public long size();

 /** This method return the perception of a zone for a player */
 public Perception getPerception(RPObject.ID id, byte type);
 /** This method is called to take zone to the next turn */
 public void nextTurn();
 /** Method to create the map to send to player's client */
 public java.util.List buildMapObjectsList(RPObject.ID id);

</verbatim>

In most of the cases all you will like to modify are:

• onInit
• onFinish
• buildMapObjectsList

!!IRPRuleProcessor This class *MUST* be implemented fully, but it is a child toy compared to IRPZone :). Here is where you code all your games rules. The API is as: <verbatim>

 /** Set the context where the actions are executed.
  *  @param zone The zone where actions happens. */
 public void setContext(IRPZone zone);
 /** Pass the whole list of actions so that it can approve or deny the actions in it.
  *  @param id the id of the object owner of the actions.
  *  @param actionList the list of actions that the player wants to execute. */
 public void approvedActions(RPObject.ID id, RPActionList actionList);
 /** Execute an action in the name of a player.
  *  @param id the id of the object owner of the actions.
  *  @param action the action to execute
  *  @return the action status, that can be Success, Fail or incomplete, please
  *      refer to Actions Explained for more info. */
 public RPAction.Status execute(RPObject.ID id, RPAction action);
 /** Notify it when a new turn happens */
 public void nextTurn();
 /** Callback method called when a new player enters in the game
  *  @param object the new player that enters in the game. */
 public boolean onInit(RPObject object) throws RPObjectInvalidException;
 /** Callback method called when a new player exits the game
  *  @param id the new player id that exits the game.
  *  @return true to update the player on database. */
 public boolean onExit(RPObject.ID id) throws RPObjectNotFoundException;
 /** Callback method called when a new player time out
  *  @param id the new player id that timeouts. */
 public boolean onTimeout(RPObject.ID id) throws RPObjectNotFoundException;

</verbatim>

!!! Questions Do you have questions? Edit the page and place here. Regards, Miguel