Marauroa Core API: Difference between revisions

{{Navigation for Marauroa Top|Using}}

{{Navigation for Marauroa Users}}

Marauroa exposes a very simplified and reduced API so you can easily develop your own games. A nightly build [http://stendhalgame.org/hudson/job/marauroa_HEAD/javadoc/ JavaDoc API Documentation] is available, too.

== Content ==

[[Image:Classdiagram_marauroa.common.game_rp_stubs.png|thumb|Class Diagram of RP* classes]]

* RPWorld

To read about these elements please see [[RolePlayingDesign]] and [[GameDesign]].

Or if you would prefer to use Python for developing the game rules read about:

* PythonWorld

The Python API can be found at [[PyArianneAPIDefinition]] and an example of its use at [[PyArianneAPIExample]]. You can read more about using Python for developing in our game tutorial [[HowToWriteGamesUsingArianne]]. Please note that Python support is dormant.

== Attributes ==

Attributes are pairs of data stored in a list. Each attribute comprises of a ''name'' and ''value'' element. Attributes are the standard way of storing data in Arianne. An example of an attribute is your age, e.g. name="age" and value=21

Each attribute also has a type associated with it that is defined in a ''RPClass''. An attributes is an instance of a ''RPClass'' (see next section of this document to read more on RPClass.

There are two special entries in attributes:

* ''type'': defines the name of the RPClass that the object belongs to.

* ''id'': defines a unique identifier

The methods exposed by the Attributes class to the game developer are shown below. These are the functions you should use to modify your attributes.

Setting the value of an attribute:

<source lang="java">

public void put(String name, String value)

public void put(String name, int value)

</source>

Add a quantity to the value element of an attribute that MUST already exist:

<source lang="java">

public void add(String name, int quantity)

</source>

Returns the value of an attribute:

<source lang="java">

public String get(String name)

public int get(String name)

</source>

Removes an attribute entry from the list of attributes:

<source lang="java">

public void remove(String name)

</source>

Returns True if an attribute exists:

<source lang="java">

public boolean has(String name)

</source>

'''Example''': <br>

<source lang="java">

Attributes test=new Attributes();

test.put("name","Test attribute");

test.put("hp",100);

if(test.has("hp")) {

test.add("hp",10);

test.remove("name");

</source>

== RPClass ==

This class is a key concept of Arianne. An RPClass is much like a Java Class but for Arianne RPObjects: it defines the type (string, int, boolean, ...) and the visibility (hidden, private or visible) of the attributes that make up an object (an object is a collection of attributes, for example for a human, age, height etc).

RPClass is made up of five different parts:

A data type 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.

The Visibility of the data:

* ''Visible'': if the attribute can be seen by clients.

* ''Hidden'': if the attribute is not visible to clients.

* ''Private'': if the attribute is only visible to the client the object is associated with (the player object controlled by this client)

Creation methods of the RPClass: (These are part of each RPClass instance, see example below for usage)

<source lang="java">

public void add(String name, byte type)

public void add(String name, byte type, byte visibility)

public void isA(String parent)

public void isA(RPClass parent)

</source>

These methods add attributes to the RPClass and set their type and visibility. You can also set the parent of this class. Of course classes without parents are possible, too.

Once the class has been filled, you can query the data using these methods. These methods allow you 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.

'''Query''':

<source lang="java">

public String getName()

public byte getType(String name)

public byte getVisibility(String name)

public boolean hasAttribute(String name)

public boolean subclassOf(String parentclass)

</source>

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

'''Class wide query''':

<source lang="java">

boolean hasRPClass(String name)

RPClass getRPClass(String name)

</source>

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

'''Example''':<br>

<source lang="java">

// a general entity with a position

RPClass objclass = new RPClass("entity");

objclass.add("x", RPClass.BYTE);

objclass.add("y", RPClass.BYTE);

// an entity specialized in players

objclass = RPClass("player");

objclass.isA("entity");

objclass.add("name", RPClass.SHORT_STRING);

objclass.add("direction", 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);

</source>

Each time you create a new RPClass, as long as you give it a name (ie: entity, player, ... ), it will be added to the system list of classes.

Notice in the example that the hidden attribute must be specified if you want the RPClass to have this property otherwise by default an attribute is visible.

Note: You can choose not to use RPClasses in your application but that increases network bandwidth usage.

== RPAction ==

RPAction is an object used to represent actions that a player wants to do.

It is up to you to create these when you design your game as they are specific to each game ( you should also define a RPClass for these ).

== RPObject and RPSlot ==

RPObjects are the containters of data in Arianne. An RPObject is an Attributes element with a list of RPSlots attached.

RPSlots are slots owned by an RPObject into which other RPObjects can be placed (like items in a backpack)

The methods of the RPObject to modify slots are:

<source lang="java">

public void addSlot(RPSlot slot)

public RPSlot getSlot(String name)

public void removeSlot(String name)

public boolean hasSlot(String name)

public Iterator slotIterator()

</source>

The above methods are used to add 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.

<source lang="java">

public RPObject.ID getID()

</source>

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

RPSlot has a simple API:

<source lang="java">

public void add(RPObject object)

public RPObject get(RPObject.ID id)

public boolean has(RPObject.ID id)

public RPObject remove(RPObject.ID id)

public void clear()

</source>

These methods modify objects in the RPSlot. The clear() method removes all the objects in the slot.

<source lang="java">

public Iterator iterator()

</source>

<source lang="java">

// create an object of RPClass player and set some attribute values

RPObject object = new RPObject("player");

object.put("name", "example");

object.put("score", 0);

// create a slot called backpack

RPSlot slot = new RPSlot("backpack");

// create an object of RPClass "coin" and put it into the slot

RPObject coin = new RPObject("coin");

slot.add(coin);

</source>

Now for the complex part. Where it all becomes a little nuts!: IRPZone and IRPRuleProcessor interfaces

==RPWorld==

This class is just a container of zones.

RPWorld provides several methods to make easier the handling of RPZones.

onInit and onFinish are called on server startup and finalization. You need to subclass RPWorld to give proper behaviour to them.

<source lang="java">

public void onInit() throws Exception

public void onFinish() throws Exception

</source>

Some helper methods to add zones and iterate them.

<source lang="java">

public void addRPZone(IRPZone zone)

public IRPZone getRPZone(IRPZone.ID zoneid)

public IRPZone getRPZone(RPObject.ID objectid)

public Iterator<IRPZone> iterator()

public int size()

</source>

Methods to add, get, test existence, remove and modify objects. modify() is as you know for delta^2 algorithm.

<source lang="java">

public void add(RPObject object) throws NoRPZoneException, RPObjectInvalidException

public RPObject get(RPObject.ID id) throws NoRPZoneException, RPObjectInvalidException

public boolean has(RPObject.ID id) throws NoRPZoneException, RPObjectInvalidException

public RPObject remove(RPObject.ID id) throws NoRPZoneException, RPObjectNotFoundException

public void modify(RPObject object) throws NoRPZoneException

</source>

These are helper methods for changing the zone of an object. Use them instead of doing it by hand.

<source lang="java">

public void changeZone(IRPZone.ID oldzoneid, IRPZone.ID newzoneid, RPObject object) throws NoRPZoneException

public void changeZone(String oldzone, String newzone, RPObject object) throws NoRPZoneException

</source>

==IRPZone==

IRPZone is the interface that handles the world content and the perceptions. In most cases you should use the implementation MarauroaRPZone and extend it.

<source lang="java">

/** This method is called when the zone is created to populate it */

</source>

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

==IRPRuleProcessor==

This class must be implemented fully, but it is a childs toy compared to IRPZone :). This is where you code all your games rules.<br>

The API is as follows:

<source lang="java">

* @param zone The zone where actions happens. */

</source>

[[Category:Marauroa]]

{{#breadcrumbs: [[Marauroa]] | [[Navigation for Marauroa Users|Using]] | [[Marauroa Core API|Core API]]}}