PyArianneAPIExample

From Arianne
Jump to: navigation, search
 [01]  import pyarianne

 [02]  def doStuffonCallback():
         print "Calling from Python!"

 [03]  world=pyarianne.World()
 [04]  perceptionHandler=pyarianne.PerceptionHandler()

       print "Starting pyclient"
 [05]  pyarianne.setIdleMethod(doStuffonCallback)
 [06]  pyarianne.connectToArianne("127.0.0.1",3214)
 [07]  if pyarianne.login("username","password"):
 [08]    chars=pyarianne.availableCharacters()

 [09]    if pyarianne.chooseCharacter(chars[0]):
          i=0
          while i<100:
 [10]	      if pyarianne.hasPerception():
 [11]	        perception=pyarianne.getPerception()
 [12]         perceptionHandler.applyPerception(perception, world)
    	        i=i+1

 [13]      pyarianne.logout()
         else:
 [14]      print "CAN'T CHOOSE: "+pyarianne.errorReason()
       else:
 [14]    print "CAN'T LOGIN: "+pyarianne.errorReason()

       print "Finishing pyclient"

This example is a bare python client that just connects to the Arianne server, recieves 100 perceptions and logs out.

Please refer to pyArianneAPIDefinition for a detailed look at the Arianne Python API.

Let see the example line by line

[01] import pyarianne
This line is used to incorporate the pyarianne module in to your application. It may be wise to check if pyarianne variable is not None after importing to check that it was loaded correctly.

[02] def doStuffonCallback():
[02] print "Calling from Python!"
In these lines we define the python function that will be called by the library each time the client is waiting to get a message. It is called mainly by: login, chooseCharacter and sendBlocking

[03] world=pyarianne.World()
This is the data structure that stores the world. It is possible that this dissapears and is hidden by the implementation, forcing you to define a nicer container for the world.

[04] perceptionHandler=pyarianne.PerceptionHandler()
This initiates the class that is in charge of handling perceptions. There is no reason why you should handle perceptions yourself.

[05] pyarianne.setIdleMethod(doStuffonCallback)
This method sets the idle method that will be called each time the application is waiting for a message.

[06] pyarianne.connectToArianne("127.0.0.1",3214)
This method initiates the network connection to the server whose IP is 127.0.0.1 and is running on port 3214. It doesn't realize any actual kind of connection, just initialises it.

[07] pyarianne.login("username","password")
This method tries to connect to the server using the username and password given. It will return true if the login was successfull or it will fail if the login was not possible, either because of an outdated client version or because of invalid login information or due to server being full or unreachable.

[08] chars=pyarianne.availableCharacters()
This method returns the list of characters that are available for this user account after login.

[09] pyarianne.chooseCharacter(chars[0])
Once you have recieved the list of characters, you can choose one of them, or you can pass it as string with the character names. The character will be your avatar in Arianne.

[10] pyarianne.hasPerception()
Ok, now comes the loop part of Arianne. You must call hasPerception to check if there is a perception available. It is a waste of processing to check for perceptions every loop; you should check only around every 1/2 turn.

[11] perception=pyarianne.getPerception()
We get the perception, as explained in the [pyArianneAPIDefinition]. Again, you shouldn't waste your time with the perception itself, just pass it to...

[12] perceptionHandler.applyPerception(perception, world)
Its tasks is to handle the perception. If we change anything you don't need to worry about it, just update PerceptionHandler and be happy :)

[13] pyarianne.logout()
When you want to leave the arianne world, it is recomended that you use logout, otherwise your character will stay on the world until it times out.

[14] pyarianne.errorReason()
You know shit happens, fact of life; errorReason will give a reason why any problems happen. In the future we will add a code number so that you can build i18n clients.