From Alcugs

Contents 1 Introduction 2 Ordinary Python Commands 3 API 4 Structures 4.1 ptAgeInfoStruct 4.2 ptAgeLinkStruct 4.3 ptAgeVault 4.4 ptAvatar 4.5 ptBook 4.6 ptNetLinkingMgr 4.7 ptSDL 4.8 ptSpawnPointInfo 4.9 ptVault 5 Tutorials 5.1 Linking To An Age 5.2 Getting notified if the user presses a key 5.3 Moving an object with mass 5.4 Using a Timer

Introduction

The Plasma Interface provides powerful access to the abilities of the Plasma engine. There is essentially nothing in the game, that you won't be able to implement through this.

Note: I may have misinterpreted the behavior of some commands, so bear with me!

Ordinary Python Commands

print 'text',  //prints the text to one of the Python.elf files, use Marack's ELF Viewer to view. The comma is optional; if used, makes the next print command follow it on the same line.
print variable,  //prints the contents of the variable, see previous line for the behavior of the comma.

API

Python
 
 PtAtTimeCallback(selfkey, time, id) #sets the timer to go off after "time" seconds.  id is used to identify the caller, and can be any integer. 4200-4299 are reservered for the UruAgeManager API.  selfkey is the key of the object to receive the message, and is usually self.key
 PtDisableMouseMovement() #apparently does nothing.
 ptDisableMovementKeys() #user cannot move.
 PtDisableRenderScene() #makes the engine stop rendering 3D graphics. 2D GUIs continue to work.
 PtEnableMovementKeys() #user can move.
 PtEnableRenderScene() #makes the engine continue rendering 3D graphics. see PtDisableRenderScene()
 PtFindSceneobject(name,ageName) #returns a ptSceneObject whose name is "name" and ageName is the filename(e.g. for Dustin.age, ageName='Dustin').  To set the name of an object in Blender, add the "name" property(string) to an object.
 PtFakeLinkAvatarToObject() #despire declaration takes 2 params.  avatars key(avatar.getKey()), and ptAttribSceneObject.value.getKey(), this will link you to somewhere else, within the same file.
 PtGetAgeInfo() #returns ptAgeInfoStruct for current age.
 PtGetAgeName() #returns filename? of current age.
 PtGetAgeSDL() #returns ptSDL? of current age.
 PtGetAgeTime() #returns an int giving the time of day for the Age in seconds.
 PtGetLocalAvatar() #returns user's avatar, not another persons. ptAvatar, if you cast it with .avatar
 PtGetLocalKILevel() #returns int for KI level, apparently at least 2 is what you need to open Gahreesen doors.
 PtGetServerTime() #returns an int giving the time in seconds, from the server(still works even in offline-mode).
 PtGUICursorDimmed() #makes the cursor slowly dim to nothingness, but it comes back if you move it.
 PtGUICursorOff() #makes the cursor invisible, but it comes back if you move it.
 PtGUICursorOn() #makes the cursor visible, if you had turned it off.
 PtSendKIMessage(command, value) #send message to KI subsystem

Structures

ptAgeInfoStruct

Python
 
    def __init__(self):
    def copyFrom(self, other):
    def getAgeFilename(self):
    def getAgeInstanceGuid(self):
    def getAgeInstanceName(self):
    def getAgeLanguage(self):
    def getAgeSequenceNumber(self):
    def getAgeUserDefinedName(self):
    def getDisplayName(self):
    def setAgeFilename(self, filename): #sets the filename, ie 'RestorationGuild'
    def setAgeInstanceGuid(self, guid):
    def setAgeInstanceName(self, instanceName): #sets the name of the instance, ie 'DustinsRelto','PublicRestorationGuild'
    def setAgeLanguage(self, lang):
    def setAgeSequenceNumber(self, seqNumber):
    def setAgeUserDefinedName(self, udName):

ptAgeLinkStruct

Python
 
    def __init__(self):
    def copyFrom(self, other):
    def getAgeInfo(self):
    def getLinkingRules(self):
    def getParentAgeFilename(self):
    def getSpawnPoint(self):
    def setAgeInfo(self, ageInfo): #use this to initialize, using a ptAgeInfoStruct.
    def setLinkingRules(self, rule): #use this to set the linking rules, where rule is a PtLinkingRules. i.e. PtLinkingRules.kOriginalBook
    def setParentAgeFilename(self, ageInfo):
    def setSpawnPoint(self, spawnPtName): #sets the spawn point for the link, a ptSpawnPointInfo .

ptAgeVault

Python
 
    def __init__(self):
    def addChronicleEntry(self, name, type, value):
    def addDevice(self, deviceName, cb, cbContext):
    def findChronicleEntry(self, entryName):
    def getAgeDevicesFolder(self):
    def getAgeGuid(self):
    def getAgeInfo(self):
    def getAgeSDL(self):
    def getAgesIOwnFolder(self):
    def getChronicleFolder(self):
    def getDevice(self, deviceName):
    def getDeviceInbox(self, deviceName):
    def getPeopleIKnowAboutFolder(self):
    def getPublicAgesFolder(self):
    def getSubAgeLink(self, ageName):
    def getSubAgesFolder(self):
    def hasDevice(self, deviceName):
    def isConnected(self):
    def removeDevice(self, deviceName):
    def setAgeGuid(self, guidString):
    def setDeviceInbox(self, deviceName, inboxName, cb, cbContext):
    def updateAgeSDL(self, pyrec):

ptAvatar

Python
 
    def __init__(self):
    def addWardrobeClothingItem(self, clothing_name, tint1, tint2):
    def enterSubWorld(self, sceneobject): #causes you to enter a subworld, this is used in gahreesen when going through the doors of the second building. sceneobject is a ptAttribSceneObject
    def exitSubWorld(self): #causes you to leave a subworld.
    def getAllWithSameMesh(self, clothing_name):
    def getAvatarClothingGroup(self): #returns group that user belongs to, i.e. kFemaleClothingGroup, kMaleClothingGroup.
    def getAvatarClothingList(self):
    def getClosetClothingList(self, clothing_type):
    def getCurrentMode(self):
    def getEntireClothingList(self, clothing_type):
    def getMatchingClothingItem(self, clothingName):
    def getMorph(self, clothing_name, layer):
    def getSkinBlend(self, layer):
    def getTintClothingItem(self, clothing_name):
    def getTintSkin(self):
    def getUniqueMeshList(self, clothing_type):
    def getWardrobeClothingList(self):
    def gotoStage(self, behaviorKey, stage, transitionTime, setTimeFlag, newTime, SetDirectionFlag, isForward, netForce):
    def netForce(self, forceFlag):
    def nextStage(self, behaviorKey, transitionTime, setTimeFlag, newTime, SetDirectionFlag, isForward, netForce):
    def oneShot(self, seekKey, duration, usePhysicsFlag, animationName, drivableFlag, reversibleFlag):
    def playSimpleAnimation(self, animName):
    def previousStage(self, behaviorKey, transitionTime, setTimeFlag, newTime, SetDirectionFlag, isForward, netForce):
    def registerForBehaviorNotify(self, selfKey):
    def removeClothingItem(self, clothing_name, update = 1):
    def runBehavior(self, behaviorKey):
    def runBehaviorSetNotify(self):
    def saveClothing(self): //saves changes, instead of temporary?
    def setMorph(self, clothing_name, layer, value):
    def setReplyKey(self, key):
    def setSkinBlend(self, layer, value):
    def tintClothingItem(self, clothing_name, tint, update = 1):
    def tintClothingItemLayer(self, clothing_name, tint, layer, update = 1):
    def tintSkin(self, tint, update = 1):
    def unRegisterForBehaviorNotify(self, selfKey):
    def wearClothingItem(self, clothing_name, update = 1):

ptBook

Python
 
    def __init__(self, esHTMLSource, coverImage = None, callbackKey = None, guiName = ''):
    def allowPageTurning(self, allow):
    def close(self):
    def closeAndHide(self):
    def getCurrentPage(self):
    def getEditableText(self):
    def getMovie(self, index):
    def goToPage(self, page):
    def hide(self):
    def nextPage(self):
    def open(self, startingPage):
    def previousPage(self):
    def setEditable(self, editable):
    def setEditableText(self, text):
    def setGUI(self, guiName):
    def setPageMargin(self, margin):
    def setSize(self, width, height):
    def show(self, startOpened):

ptNetLinkingMgr

Python
 
    def __init__(self):
    def getCurrAgeLink(self):
    def getPrevAgeLink(self):
    def isEnabled(self):
    def linkPlayerHere(self, pid):
    def linkPlayerToAge(self, ageLink, pid):
    def linkToAge(self, ageLink): #links to ageLink, a ptAgeLinkStruct.
    def linkToMyNeighborhoodAge(self):
    def linkToMyPersonalAge(self): #links to Relto, but doesn't show hand on book?
    def linkToMyPersonalAgeWithYeeshaBook(self): #links to Relto, showing hand on book?
    def linkToPlayersAge(self, pid):
    def setEnabled(self, enable):

ptSDL

Allows you to write to savestate.

Python
 
    def __init__(self):
    def sendToClients(self, key):
    def setDefault(self, key, value):
    def setFlags(self, name, sendImmediate, skipOwnershipCheck):
    def setIndex(self, key, idx, value): #sets a value for key at index idx of value. e.g. ('LidOpen',0,1) to set the lid open. ('LidOpen',0,0) to set it closed.
    def setIndexNow(self, key, idx, value):
    def setNotify(self, selfkey, key, tolerance):
    def setTagString(self, name, tag):

ptSpawnPointInfo

Python
 
    def __init__(self, title = None, spawnPt = None): #constructor, allows you to set title and name, e.g. title='Garden' name='LinkInPointDefault'
    def getCameraStack(self):
    def getName(self):
    def getTitle(self):
    def setCameraStack(self, v):
    def setName(self, v):
    def setTitle(self, v):

ptVault

Python
 
    def __init__(self):
    def addChronicleEntry(self, entryName, type, string):
    def amAgeCzar(self, ageInfo):
    def amAgeOwner(self, ageInfo):
    def amCzarOfCurrentAge(self):
    def amOwnerOfCurrentAge(self):
    def createNeighborhood(self):
    def findChronicleEntry(self, entryName):
    def findNode(self, templateNode):
    def getAgeJournalsFolder(self):
    def getAgesICanVisitFolder(self):
    def getAgesIOwnFolder(self):
    def getAvatarClosetFolder(self):
    def getAvatarOutfitFolder(self):
    def getBuddyListFolder(self):
    def getChronicleFolder(self):
    def getGlobalInbox(self):
    def getIgnoreListFolder(self):
    def getInbox(self):
    def getInviteFolder(self):
    def getKIUsage(self):
    def getLinkToCity(self):
    def getLinkToMyNeighborhood(self):
    def getOwnedAgeLink(self): #despite declaration, should take ptAgeInfoStruct as param.
    def getPeopleIKnowAboutFolder(self):
    def getPlayerInfo(self):
    def getPsnlAgeSDL(self):
    def getVisitAgeLink(self, ageInfo):
    def inMyNeighborhoodAge(self):
    def inMyPersonalAge(self):
    def invitePlayerToAge(self, link, playerID):
    def isConnected(self):
    def offerLinkToPlayer(self, link, playerID):
    def registerMTStation(self, stationName, mtSpawnPoint):
    def registerOwnedAge(self, link): #register link as an owned age. link is ptAgeInfoStruct
    def registerVisitAge(self, link):
    def removeOwnedAgeLink(self, guidstr):
    def removeVisitAgeLink(self, guidstr):
    def sendToDevice(self, node, deviceName):
    def setAgePublic(self, ageInfo, makePublic):
    def unInvitePlayerToAge(self, guid, playerID):
    def unRegisterOwnedAge(self, ageFilename):
    def unRegisterVisitAge(self, guid):
    def updatePsnlAgeSDL(self, pyrec):

Tutorials

Note: If you do not know python or plan to introduce advanced functionality in your age, please contact an Alcugs Developer who has advanced experience with the Plasma Python API.

Linking To An Age

Python
 
# In a ptAgeInfoStruct, we put the Age's filename and, if we want, the instance name.
# In a ptSpawnPointInfo we put the spawn point title and name.  The name is the important part.
# In a ptAgeLinkStruct, we load the ptAgeInfoStruct, then put the [[LinkingRules|'''linking rules''']], then load the ptSpawnPointInfo.
# Then we use a ptNetLinkingMgr to link to the Age!
 
 from Plasma import *
 from PlasmaNetConstants import *
 
 agelink = ptAgeLinkStruct()
 ageinfo = ptAgeInfoStruct()
 ageinfo.setAgeFilename("Dustin") #if you filename were Dustin.age
 # ageinfo.setAgeInstanceName("PublicDustin") would go here, if I were using it.
 spawnpoint = ptSpawnPointInfo("spawnpointtitle","LinkInPointDefault") # the spawnpointtitle doesn't really matter.
 agelink.setAgeInfo(ageinfo)
 agelink.setLinkingRules(PtLinkingRules.kOriginalBook) #The various linking rules can be found in PlasmaNetConstants.py
 agelink.setSpawnPoint(spawnpoint)
 linkmanager = ptNetLinkingMgr()
 linkmanager.linkToAge(agelink)

Getting notified if the user presses a key

Python
 
 import PlasmaControlKeys  #required at the beginning of Python file.
 
 PtGetControlEvents(true, self.key) #turns on notification of key presses.
 
 PtGetControlEvents(false, self.key) #turns off notification of key presses.
 
 def OnControlKeyEvent(self, controlKey, activeFlag): #this function is called whenever a key is pressed.
     if (activeFlag==true): #activeFlag tells you whether the key is up or down.
         print 'key just went down'
     else:
         print 'key just went up'
     if (controlKey==PlasmaControlKeys.kKeyActionMouse): #controlKey tells you which key was involved.
         print 'left mouse button just went up or down.'
     if (controlKey==PlasmaControlKeys.kKeyExitMode):
         print 'Escape key just went up or down.'
     if (controlKey==PlasmaControlKeys.kKeyMoveBackward):
         print 'DownArrow key just went up or down.'

The complete list of keys that you can detect can be found in PlasmaControlKeys.py . Feel free to add any keys that you have figured out. The keys I name are the default mapping. The user may have changed which button jumps, and which button moves forward, etc.

You might want to put the PtGetControlEvents(true,self.key) in the OnServerInit function.

Moving an object with mass

The object must have a mass, since it must be treated by the Havoc physics engine.

You can set the name of an object in Blender, by adding the property "name"(make the type a string). So you can set the string property "name"="DustinSphere1".

Python
 
 t = PtFindSceneobject("objectName", "ageFileName")
 #For example, if I had Dustin.age and my object was named "DustinSphere1", I would use:
 t = PtFindSceneobject("DustinSphere1", "Dustin")
 t.physics.suppress(true) #turns off physics for the object(so that it doesn't fall, for example)
 t.physics.suppress(false) #turns on physics for the object( so that it will fall, for example)
 p = ptPoint3(0.0, 1.0, 2.3) #names a coordinate point. x=0.0, y=1.0, z=2.3
 t.physics.warp(p) #Moves the object t to position p.

Using a Timer

Python
 
 PtAtTimeCallback(self.key, 4.2, 4) #Tells the timer to go off in 4.2 seconds, with id=4
 
 def OnTimer(self, id):
     #id is 4 in this example.
     #The timer went off once, but it won't go off again unless we tell it to.
     #To make the timer go off in another 4.2 seconds we should:
     PtAtTimeCallback(self.key,4.2,4)

We can effectively have as many timers as we want. We use the id to know which "timer" went off, by using a different id for each "timer".