PyArianneAPIDefinition

pyarianne API

pyarianne is the API that connects your game to the Arianne system. For an example of how to use this API, please just go to the pyArianneAPIExample page.

It is composed of several functions that provide you with basic, low level access in to the Arianne framework.

It is important that you respect the order of the functions; if not the behaviour of your application will be irratic.

Let's first have a look at the function calls and we will describe the data structures later.

• setIdleMethod(function)
  

This function sets the callback function that will be called each time the module needs to block for a given period of time. The callback function should return true to make the pyarianne module continue wait for data, and false will make the modile stop waiting.

  def callbackFunction():
     return 1;

  pyarianne.setIdleMethod(callbackMethod)

• connectToArianne(serverName, port)
  

This function is called to connect to an Arianne server running on the server whose name (DNS) or IP is <serverName> and that can be reached at port <port>. This function will never fail. It returns nothing

  pyarianne.connectToArianne("gladiators.game-server.cc",3214)

• login(username, password)
  

This function should be called AFTER connecting to the Arianne server; it tries to login to the server using the given username and password combination. It will return true if the login is completed successfully or false if there is a problem and it then will set error to true. This function blocks up to 4 seconds before failing.

  if pyarianne.login("superuser","pazzw0rd"):
    print "Logged into the server"
  else:
    print "Failed to login into the server"

• availableCharacters()
  

Once you have logged into Arianne, you can get the list of characters available for your account. It will return a list of name of characters.

  chararacters=pyarianne.availableCharacters()

• serverInfo()
  

Once you have logged into Arianne, you can get the list of server properties that may be relevant to the client. It will return a list of properties of the form attribute=value.

  serverInformation=pyarianne.availableCharacters()

• getGameType()
  

Returns a string containing the type of game we are playing.

  if not pyarianne.getGameType()='mapacman':
    System.exit(-1)

• chooseCharacter(character)
  

Once have recieved the list of characters you can choose one of them that you will use to enter the game. If it enters correctly it will return true, otherwise it will return false. This function blocks for up to 4 seconds before it fails.

  if pyarianne.chooseCharacter("massivePain"):
    print "Character choosen"
  else:
    print "Unable to choose character"

• hasRPMap()
  

This function returns true if there is a Map available for this game.

• getRPMap()
  

This functions returns a list of objects containing the data of the Map. It is up to your client to process it and build an appropriate representation.

• hasPerception()
  

This function returns true if there is a perception available for your game.

• getPerception()
  

This function returns a perception that should have been previously stored by a call to hasPerception, using a polling technique. This function won't block the client.

  if pygame.hasPerception():
    perception=pygame.getPerception()

• send(action)
  
• sendBlocking(action)
  

Both these functions send an Action the server, but the blocking function will block until the server replies with a Action ACK message, which will be around the length of the trip time of the message. They return nothing.

  action=pygame.RPAction()
  action.put("type","kill")
  action.put("target","~*")

  pygame.send(action)

• logout()
  

Exits the Arianne enviroment and returns true. If it returns false it means the logout didn't happened. This function blocks for up to 4 seconds before it fails.

  pygame.logout()

• iserror()
  

Return true if there is a significant error

• errorReason()
  

Returns a string containing an explanation of the error.

There are also several structures which are very important in the game. These MUST be used at some point.

• RPAction
• RPObject
• RPSlot
• Perception
• World
• PerceptionHandler

RPAction

We use RPAction to tell the server to do something with our characters. Depending on the game different actions will be accomplished.

It has several methods:

• has(attribute)
  

Returns true if the action has the attibute whose name matches attribute.

• put(attribute, value)
  

Sets an attribute in the action where attribute's name is attribute and value is value. Value can either be a string or a number.

• get(attribute)
  

Returns a string containing the value of the attribute This method will fail if it is called on a attribute that doesn't exist.

• getInt(attribute)
  

Returns an integer containing the value of the attribute This method will fail if it is called on a attribute that doesn't exist.

• remove(attribute)
  

Removes an attribute from the action or fails if it doesn't exist.

• clear()
  

Remove all the attributes from the action

• equals(action)
  

Return true if the action is equal to this action.

• toString()
  

Return a string representation of the action

• size()
  

Returns the number of attributes of the action

RPObject

This class represents RPObjects in the world, everything in Arianne is an object, keep that in mind.

It has several methods:

• has(attribute)
  

Returns true if the object has the attibute whose name matches attribute.

• put(attribute, value)
  

Sets an attribute in the object where attribute's name is attribute and value is value. Value can either be a string or a number.

• get(attribute)
  

Returns a string containing the value of the attribute This method will fail if it is called on a attribute that doesn't exist.

• getInt(attribute)
  

Returns an integer containing the value of the attribute This method will fail if it is called on a attribute that doesn't exist.

• remove(attribute)
  

Removes an attribute from the object or fails if it doesn't exist.

• clear()
  

Removes all the attributes from the object

• equals(object)
  

Returns true if the object is equals to this object.

• toString()
  

Returns a string representation of the object

• size()
  

Returns the number of attributes of the object plus all the attributes of the objects that exist in the slots.

• addSlot(slot)
  

Add an RPSlot to the object; it will fail if the slot already exists on the object. So if you want to replace a slot, first remove the current slot.

• getSlot(name)
  

Returns an RPSlot from the Object whose name is name. It will fail if there is no such slot.

• removeSlot(name)
  

Removes the slot from the object whose name is name. It will fail if there is no such slot.

• hasSlot(name)
  

Returns true if the object has a slot named name.

• applyAddedDifferences(added)
  
• applyDeletedDifferences(deleted)
  
• removeAllHidden()
  

Don't use these methods directly. See PerceptionHandler.

RPSlot

Every object can be a slot, they are like extensions of an object that allow it to contains more objects. A pocket, a bag, a chest are examples of objects.

It has several methods:

• name
  

It contains the name of the Slot. It is a string.

• add(object)
  

This method adds an object to the slot or replaces it if it exists.

• get(id)
  

Returns the object whose id is id or fails if there is no such object.

• getByPosition(i)
  

Returns the object whose position on the list of objects is i or fails if there is no such position

• has(id)
  

Returns true if there is an object whose id is id. False otherwise

• remove(id)
  

Removes the object whose id is id or fails if it can't be found-

• clear()
  

Removes all the objects in the slot.

• equals(slot)
  

Return true if the slot is equals to this slot.

• toString()
  

Return a string representation of the slot

• size()
  

Returns the number of objects in the slot.

Perception

A perception is the basic unit of information of the Arianne system. You get one perception each turn and basically there are two different classes of perception:

• SYNC
  These are sent to synchronize the client with the server, for example, after login or after a few failures on the connection.
• DELTA
  These are sent to the client each turn to tell it the differences with the previous status of the world.

Of course you can and must ignore such lowlevel details when using pyarianne.
It contains:

• type
  

It is an enum type that can be either 0 or 1 to indicate SYNC and DELTA perception type.

• timestamp
  

It is a constant incremental counter to mark each perception

• added
  
• modifiedAdded
  
• modifiedDeleted
  
• deleted
  

These are a list of RPObjects that contain added, modified added, modified deleted and deleted objects respectively

• myRPObjectChanged
  

It is a boolean value that will be true if myRPObject contains a valid value

• myRPObject
  

It is our RPObject containing all the hidden attributes.

Again, you should never use this structure directly, but instead use PerceptionHandler

World

This is a container for objects that must be use by PerceptionHandler. For a unknown reason if this structure is written in Python it is not understood by SWIG and objects are freed :(

• objects_
  

It is a dict of integer<-->RPObject

PerceptionHandler

This is the class that cares about perception handling, and this is the only thing you should ever use to handle a perception. The class is very simple, it has a constructor a method to handle the perception and modify the world.

• PerceptionHandler(listener)
  

It is passed an instance of a subclass of ~PerceptionListener that handles everything related to the perception on a detailed way. You can choose to implement your own, or use the default one.

• apply(perception, world)
  

Just call this method with the perception you get from getPerception and the world where objects are stored, and voila... perception gets applied.

• PerceptionListener
  

It is a listener class for handling perceptions. Each method is called on the given event, you can execute whatever you want inside.

• onAdded(object)
  

It is called when an object is added to the world.

• onBeforeModifiedAdded(object, previous)
  

It is called when an object is modified by adding slots or attributes.

• onBeforeModifiedDeleted(object, previous)
  

It is called when an object is modified by removing slots or attributes.

• onModifiedAdded(object)
  

It is called when an object has been modified by adding slots or attributes.

• onModifiedDeleted(object)
  

It is called when an object has been modified by removing slots or attributes.

• onDeleted(object)
  

It is called when an object is deleted of the world

• onMyRPObject(changed, object)
  

It is called on each perception, if changed is true, object contains the resulting new object for our character, else it will contains None

• onPerception()
  

It is called on each perception.

• onClear()
  

It is called each time the whole world is emptied

• onUnsync()
  

When you get out of sync this method is called

• onSync()
  

When you recover sync with server this method is called

That's all.
There is nothing more to this API, please just go to the pyArianneAPIExample for more info.