Arianne

Marauroa Core API: Difference between revisions

← Older edit
Content deleted Content added
VisualWikitext
imported>Hendrik Brummermann
imported>Blacklads
Undo revision 11663 by Ufizavipupu (Talk)
 
(98 intermediate revisions by 3 users not shown)
Line 1:
{{Navigation for Marauroa Top|InternalsUsing}}
{{Navigation for Marauroa DevelopersUsers}}
 
 
Marauroa exposes a very simplified and reduced API so you can easily develop your own games. A nightly build [http://stendhal.game-hoststendhalgame.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]]
 
The main entities you should know about are:
* Attributes
Line 22 ⟶ 24:
* 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 ==
Line 101 ⟶ 103:
</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, however,classes awithout classparents canare have no parent (bepossible, parentless)too.
 
Once the class has been filled, you can query the data using these methods. These methods alowallow 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.<br>▼
 
▲Once the class has been filled, you can query the data using these methods. These methods alow 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.<br>
'''Query''':
<source lang="java">
Line 113 ⟶ 116:
</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!<br>
 
'''Class wide query''':
<source lang="java">
* '' boolean hasRPClass(String name)''
* '' RPClass getRPClass(String name)''
</source>
 
Line 128 ⟶ 132:
// 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("dirdirection", 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: playerentity, positionplayer, ... ), it will be added to the system list of classes.
 
Notice in the example that the HIDDENhidden 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 BUTbut thethat performanceincreases penalty will be big onnetwork bandwidth and CPU usage.
 
== RPAction ==
Line 154 ⟶ 158:
 
== RPObject and RPSlot ==
RPObjects are the containters of data in Arianne. An RPObject is an (''isa'' function) Attributes element with a list of RPSlots attached. <br>
 
RPSlots are slots on objects that items can be placed on/in, such as backpacks, pockets, boxes, ...<br>
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)''
* ''RPSlot getSlot(String name)''
* ''void removeSlot public RPSlot getSlot(String name)''
* ''boolean hasSlot 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 class elements also havehas a simple API:
<source lang="java">
* void add(RPObject object)
* RPObject get public void add(RPObject.ID idobject)
* boolean has public RPObject get(RPObject.ID id)
* RPObject remove public boolean has(RPObject.ID id)
public RPObject remove(RPObject.ID id)
* public void clear()
These methods modify objects in the RPSlot.▼
</source>
The clear() method removes all the objects in the slot.
 
▲These methods modify objects in the RPSlot. The clear() method removes all the objects in the slot.
* Iterator iterator()▼
 
<source lang="java">
▲* public Iterator iterator()
</source>
 
It is used to visit all the objects of the slot.
 
<source lang="java">
<pre>
RPObject// create an object=new RPObject(of RPClass.getRPClass(" player")); and set some attribute values
RPObject object.put = new RPObject("name","exampleplayer");
object.put("scorename",0 "example");
coinobject.put("typescore","coin" 0);▼
 
RPSlot// create a slot=new RPSlot("called backpack");
RPObjectRPSlot slot coin= new RPObjectRPSlot("backpack");
▲ coin.put("type","coin");
slot.add(coin);▼
object.addSlot(slot);
 
</pre>
// 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.
 
Line 201 ⟶ 218:
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 onFinishonInit() throws Exception
▲ public void onInitonFinish() throws Exception
</source>
 
Some helper methods to add zones and iterate them.
 
<source lang="java">
public void addRPZone(IRPZone zone)
public IRPZonevoid getRPZoneaddRPZone(IRPZone.ID zoneidzone)
public IRPZone getRPZone(RPObjectIRPZone.ID objectidzoneid)
public Iterator<IRPZone> iteratorgetRPZone(RPObject.ID objectid)
public intIterator<IRPZone> sizeiterator()
public int size()
</source>
 
Methods to add, get, test existence, remove and modify objects. modify() is as you know for delta^2 algorithm.
Modify is as you know for delta^2 algorithm.
 
<source lang="java">
public void add(RPObject object) throws NoRPZoneException, RPObjectInvalidException ▼
public RPObjectvoid getadd(RPObject.ID idobject) throws NoRPZoneException, RPObjectInvalidException
public booleanRPObject hasget(RPObject.ID id) throws NoRPZoneException, RPObjectInvalidException
public RPObjectboolean removehas(RPObject.ID id) throws NoRPZoneException, RPObjectNotFoundExceptionRPObjectInvalidException
public voidRPObject modifyremove(RPObject.ID objectid) throws NoRPZoneException, RPObjectNotFoundException
▲ public void addmodify(RPObject object) throws NoRPZoneException, RPObjectInvalidException
</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(StringIRPZone.ID oldzoneoldzoneid, StringIRPZone.ID newzonenewzoneid, RPObject object) throws NoRPZoneException
▲ public void changeZone(IRPZone.IDString oldzoneidoldzone, IRPZone.IDString newzoneidnewzone, RPObject object) throws NoRPZoneException
</source>
 
==IRPZone==▼
IRPZone is the classinterface that handles the world content and the perceptions. ItIn wouldmost becases wiseyou toshould forgetuse aboutthe it, or extendimplementation MarauroaRPZone insteadand asextend it's a complex and error prone class. <br>▼
 
▲=IRPZone=
▲IRPZone is the class that handles the world content and the perceptions. It would be wise to forget about it, or extend MarauroaRPZone instead as it's a complex and error prone class. <br>
The methods are:
<source lang="java">
<pre>
/** This method is called when the zone is created to populate 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;
Line 237 ⟶ 263:
/** 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);
Line 251 ⟶ 281:
/** Iterates over the elements of the zone */
public Iterator iterator();
 
/** Returns the number of elements of the zone */
public long size();
Line 256 ⟶ 287:
/** 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);
</presource>
 
In most of the cases all you will wish to modify are:
Line 267 ⟶ 300:
* buildMapObjectsList
 
==IRPRuleProcessor==▼
 
This class *MUST*must be implemented fully, but it is a childs toy compared to IRPZone :). This is where you code all your games rules.<br>▼
▲=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">
<pre>
/** 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.
Line 285 ⟶ 319:
* 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;
</presource>
 
[[Category:Marauroa]]
{{#breadcrumbs: [[Marauroa]] | [[Navigation for Marauroa Users|Using]] | [[Marauroa Core API|Core API]]}}
Retrieved from "https://meet.konsthol.eu/w/index.php?title=Marauroa_Core_API"