UruAgeManager API

Introduction

The UruAgeManager API is meant to be a library of Python functions that are simple and easy-to-use. Besides saving you time, and the hassle of trying to figure it out for yourself, the API ensures that you do tricky things properly.

Using the API

All you need to do, to use the API is include the following line at the start:

from UruAgeManager import *

Important Notes

If you use an event handler, such as:

    def OnNotify(self, state, id, events):
        uam.handleNotify(state,id,events)
        #your code.

You must keep in mind that your code will still receive all events.

Commands

output

uam.output( item1, ...)

This writes all the items to the file: "UruAgeManager.out". It flushes the file after every write, so you're guaranteed of getting the output, even if Uru crashes. Using "print" doesn't do this.

//e.g.
uam.output('hi')
uam.output(2,3.23,'hi',varX)

SDL stuff

To initialise an SDL variable, call initSDL. This will ensure that you will be notified if an SDL variable is changed.

uam.initSDL('varName', self.key)

To set an SDL variable, call:

uam.setSDL('varName', value)

To get an SDL variable, call:

result = uam.getSDL('varName')

You must have the following method in your Python file, to be notified if an SDL variable is changed:

    def OnSDLNotify(self, VARname, SDLname, playerID, tag):

In fact, if you want to change something, you should just set the SDL variable, and not do anything right away. Do the thing you want to do, in the OnSDLNotify method.(You will be notified, even if you are the one who sets the variable.)

isObjectInRange

This function will return whether or not the sceneObject is within range units of the avatar's feet.

uam.isObjectInRange(sceneObject, range)

The units used in "range" appear to be measured in feet. It can be a float. The sceneObject must be a ptSceneobject, probably got by PtFindSceneobject.

linkToAge

uam.linkToAge('ageName', 'spawnPoint')

This function will link your avatar to the given ageName and spawnPoint.
You are responsible for ensuring that the Age is installed, before you call this.

#e.g.
if(uam.isAgeInstalled('Dustin2'))
    uam.linkToAge('Dustin2') 

Age functions

To find out whether an Age is installed or not, use:

uam.isAgeInstalled('ageName')

//e.g.
if (uam.isAgeInstalled('Dustin2'))
    uam.output('The Second Age of Dustin is installed.')

To get a list of all the unofficial, installed Ages, use:

uam.getListOfAges()

It returns a Python "list" of the Age names.(e.g. ['Dustin2', 'Dustin'])

Unofficial Book Fields

Use these functions to get data about a certain Age. These all return a string. If there is no entry, it returns "". You must be prepared for a return value of "".

uam.getSpawnpoint('ageName')
uam.getDescription('ageName')
uam.getText('ageName')
uam.getFlyby('ageName')
uam.getLinkingImage('ageName')

Books

These books all use the Plasma Engine HTML. You may use the "cover" tag to have a cover on the book.

uam.showNotebook('content html', self.key)

This function shows a lined notebook.

uam.showBahroStone('content html', self.key)

This function shows a Bahro stone. Note that the first page is actually a small area in the lower right of the stone; the second page is the main part.

uam.showBook('content html', self.key)

This function shows an ordinary book(either a journal or a Linking Book). You can use it as a Linking Book, if you want added control; however, you should probably use "uam.useAgeBook".

#example:
uam.showNotebook('<font size=10 face=Atrus >This is page 1<pb>This is page 2<pb>Last Page!', self.key)

Linking Books

uam.useAgeBook('ageName', self.key, cover=None, linkingImage=None, showText=false, showFlyby=false )

This function shows the Linking Book for 'ageName', and allows the user to link to that Age. The last 4 parameters are all optional. "cover" specifies the texture to use as a cover. "linkingImage" specifies the texture to use as the Linking Panel. "showText" specifies whether the text that is in the Unofficial Ages book appears in this book. "showFlyby" specifies whether the flyby .bik file is played when the linking image is clicked.
You must have the following method in your Python file:

    def OnNotify(self, state, id, events):
        uam.handleNotify(state,id,events)

If you have showFlyby set to true, then you must all have the following methods in your Python file:

    def OnControlKeyEvent(self, controlKey, activeFlag):
        uam.handleControlKeyEvent(controlKey,activeFlag)
    def OnTimer(self, id):
        uam.handleTimer(id)
    def OnMovieEvent(self, movieName, reason):
        uam.handleMovieEvent(movieName,reason)
    def OnServerInitComplete(self):
        PtGetControlEvents(true,self.key)

The Age does not have to be installed. If it isn't installed, the book will tell the user that, and won't allow them to link.

#example
uam.useAgeBook('Dustin2', self.key)

#another example
uam.useAgeBook('Dustin2', self.key, cover='noMipMapBrownCov.jpg', showText=true)