Client Scripting API - ClientAPI

From Multiverse

Jump to: navigation, search
The Client Scripting API is under development. During this phase of development, we are focusing on functionality and features, rather than maintaining 100% backwards compatibility for each release. If you write scripts using this API, be prepared to make change them until the Client Scripting API is more stable.


Client Scripting API
ClientAPI Module

AmbientLight
AnimableValue
Animation
AnimationState
Camera
ColorEx
Compositor
Decal
DefaultInputHandler
FogConfig
GuiInputHandler
HardwareCaps
Interface

Light
Material
Model
MorphAnimationTrack
MorphKeyFrame
Network
NodeAnimationTrack
NodeKeyFrame
OceanConfig
ParticleSystem
Pass
PropertyAnimationTrack
PropertyKeyFrame

Quaternion
RaySceneQuery
RaySceneQueryResult
SceneNode
ShadowConfig
SoundSource
SystemStatus
Technique
TextureUnit
Vector3
Voice
World
WorldObject

Character Creation Framework
CharacterCreation CharacterCreationContext CharacterSelectionContext
Video and Web Content

Movie
MovieCodec

MovieManager
MovieTexture

MovieTextureManager
WebBrowser

The ClientAPI module is the entry point for the Client Scripting API.

Contents

[edit]

Functions

[edit]

Exit 

ClientAPI.Exit()

Notify the client that it should shut down. This sets an internal flag so that the client can shut down gracefully as soon as it is possible to do so.

Returns

None

Parameters

None

[edit]

FetchRemoteTexture 

ClientAPI.FetchRemoteTexture( url, textureName, handler, destWidth, destHeight, keepAspect, fillColor )

This function fetchs an image from the world wide web, turns it into a texture, and then calls a function to notify your script code that the texture is ready.

Returns

None

Parameters

Parameter Datatype Default Value Description
url string None The URL of the image to fetch. Only http URLs are currently supported. The URL must refer to a jpeg, gif, or png image.
textureName string None The name of the texture that will be created. Must be unique.
handler function None The function called when the texture has been loaded. The function must take four arguments: a string that is textureName, an integer that is the original width of the fetched image, an integer that is the original height of the fetched image and a boolean, that is True if the texture was created and False if the operation failed.
destWidth int 0 The width of the texture to be created. If this parameter is 0 then the image's original width will be used. Note that some graphics cards require textures to be power of two sizes and have limits on maximum texture size, so care should be taken when loading unknown images.
destHeight int 0 The height of the texture to be created. If this parameter is 0 then the image's original height will be used. Note that some graphics cards require textures to be power of two sizes and have limits on maximum texture size, so care should be taken when loading unknown images.
keepAspect bool False If False (the default), then the image is scaled to fill the texture. If True, then the image is scaled to keep its original aspect ratio, with any remaining space in the texture being filled with fillColor.
fillColor ClientAPI.ColorEx ClientAPI.ColorEx.Black The color to fill when keepAspect is set to True.
[edit]

GetCharacterEntries 

charEntries = ClientAPI.GetCharacterEntries()

Get the list of characters that were provided by the remote server. This is a dictionary that contains the properties of the character.

Returns

A dictionary of CharacterEntry objects, defined on the server.

Need to provide more information on how the CharacterEntry objects are defined.

Parameters

None

[edit]

GetClientParameter 

val = ClientAPI.GetClientParameter(parameterName)

Returns the value of the specified client parameter.

Returns

string

Parameters

Parameter Datatype Default Value Description
parameterName string None The name of the parameter for which we are retrieving the value (for example, Camera.PlayerVisible).
[edit]

GetCurrentTarget

NOTE: GetCurrentTarget has been moved to MarsTarget.


worldObj = ClientAPI.GetCurrentTarget()

Returns the WorldObject of the currently selected target.

Returns

WorldObject

Parameters

None

[edit]

GetCurrentTime

timeInMilliseconds = ClientAPI.GetCurrentTime()

Returns the current time in millseconds.

Returns

long

Parameters

None

[edit]

GetLocalOID 

oid = ClientAPI.GetLocalOID()

Return a unique OID that is local to the current client. It is guaranteed not to conflict with an OID generated by the server.

Returns

long

Parameters

None

[edit]

GetMaterial 

material = ClientAPI.GetMaterial(name)

Returns the named Material, or None if the material does not exist.

Returns

Material or None

Parameters

Parameter Datatype Default Value Description
name string None The name of the material to return.
[edit]

GetMaterialScheme 

schemeName = ClientAPI.GetMaterialScheme()

Returns the name of the current material scheme.

Returns

string

Parameters

None

[edit]

GetMouseoverTarget 

worldObj = ClientAPI.GetMouseoverTarget()

Returns the WorldObject that is under the cursor, or None if there is not an object under the cursor.

NOTE: This method will work only for targetable objects. A targetable object is any mob (including other players, but not your avatar) and any non-mob object that has had its WorldObject.Targetable property set to True.

Returns

WorldObject

Parameters

None

[edit]

GetMousePosition 

x, y = ClientAPI.GetMousePosition()

Returns the mouse position in the 3D window in pixels.

Returns

(float, float)

Parameters

None

[edit]

GetObjectByName

This Client scripting API method, property, or object is deprecated. Although it still works in the current release, it may not work in future releases. Instead, use ClientAPI.World.GetObjectByName(). 
obj = ClientAPI.GetObjectByName("avatar")

Returns object corresponding to the string parameter.

Returns

Object

Parameters

String object name.

[edit]

GetObjectByOID

This Client scripting API method, property, or object is deprecated. Although it still works in the current release, it may not work in future releases. Instead, use ClientAPI.World.GetObjectByOID(). 
worldObj = ClientAPI.GetObjectByOID(oid)

Returns the WorldObject associated with the given oid.

Returns

WorldObject

Parameters

Parameter Datatype Default Value Description
oid long None The object ID to look up.
[edit]

GetPlayerCamera 

camera = ClientAPI.GetPlayerCamera()

Returns the main camera for the scene. Currently this is the only supported camera.

Returns

Camera

Parameters

None

[edit]

GetPlayerObject 

worldObj = ClientAPI.GetPlayerObject()

Returns the WorldObject of the player's avatar.

Returns

WorldObject

Parameters

None

[edit]

GetScreenPosition 

x, y = ClientAPI.GetScreenPosition(target)

Get the screen coordinates where a ray from the camera origin to the target would pass through the near clip plane (or the screen).

Returns

(float, float)

Parameters

Parameter Datatype Default Value Description
target Vector3 None The position of the target of the ray in the world.
[edit]

GetScreenSize

This Client scripting API method, property, or object is deprecated. Although it still works in the current release, it may not work in future releases. Instead, use WindowSize property of HardwareCaps. 
x, y = ClientAPI.GetScreenSize()

Returns the size of the 3D window in pixels.

Returns

(float, float)

Parameters

None

[edit]

GetSoundSource 

soundSource = ClientAPI.GetSoundSource(soundFile, position, [looping], [gain], [ambient], [local])

Creates a new SoundSource object.

Returns

SoundSource

Parameters

Parameter Datatype Default Value Description
soundFile string None The name of the sound file to load. Currently supported sound files are wav/pcm and ogg/vorbis.
position Vector3 None The position in the world to place the sound source.
looping bool False Optional. Whether the sound should loop until cancelled or play once and stop.
gain float 1.0 Optional. The amount to amplify the volume of the sound. The default value of 1.0 plays the sound at its recorded volume.
ambient bool False Optional. Whether the sound is an ambient (non positional) sound. Ambient sounds are are not affected by 3D position in the world.
local bool True Optional. Whether the sound is in a file in the asset repository (local), or is being streamed from a remote server.
[edit]

GetTerrainHeight

This Client scripting API method, property, or object is deprecated. Although it still works in the current release, it may not work in future releases. Instead, use ClientAPI.World.GetTerrainHeight(). 
height = ClientAPI.GetTerrainHeight(x, z)

Returns the Y coordinate (height) of the terrain at the given X and Z coordinates.

Returns

float

Parameters

Parameter Datatype Default Value Description
x float None The X coordinate of the location to get the height.
z float None The Z coordinate of the location to get the height.
[edit]

GetTerrainHeightVector

This Client scripting API method, property, or object is deprecated. Although it still works in the current release, it may not work in future releases. Instead, use ClientAPI.World.GetTerrainHeightVector(). 
retVector = ClientAPI.GetTerrainHeight(loc)

Returns a vector containing the X and Z values of loc and the Y value of the height of the terrain at that X and Z location.

Returns

Vector3

Parameters

Parameter Datatype Default Value Description
loc Vector3 None A vector containing the X and Z values of the terrain location. The Y value is ignored.
[edit]

GrabPlayerCamera 

ClientAPI.GrabPlayerCamera()

Informs the client that a script will be moving the camera, so that the client will stop updating the camera location and orientation. When you are done manipulating the camera, you can call ReleasePlayerCamera() to return control of the camera to the client.

Returns

None

Parameters

None

[edit]

InvokeEffect

This Client scripting API method, property, or object is deprecated. Although it still works in the current release, it may not work in future releases. Instead, use ClientAPI.World.InvokeEffect(). 
ClientAPI.InvokeEffect(effectName, oid, args)

Invokes the named coordinated effect.

Returns

None

Parameters

Parameter Datatype Default Value Description
effectName string None The name of the effect.
oid long None The unique object ID for the new instance of the effect.
args dictionary None A dictionary that contains the named arguments of the effect.
[edit]

IsWorldLocal

This Client scripting API method, property, or object is deprecated. Although it still works in the current release, it may not work in future releases. Instead, use ClientAPI.World.IsWorldLocal. 
isLocal = ClientAPI.IsWorldLocal()

Exposes the client flag that indicates whether we are using a locally created world. This allows scripts to tell if we are communicating with the world server, or just showing a local scene.

Returns

bool

Parameters

None

[edit]

LaunchBrowser 

ClientAPI.LaunchBrowser(url)

Launch a web browser in a separate window and load the given URL. Note: only HTTP and HTTPS URLs are supported.

Returns

None

Parameters

Parameter Datatype Default Value Description
url string None The URL to load.
[edit]

Log 

ClientAPI.Log(message)

Writes message to the client log file, MultiverseClient.log. This method will log with a log level of INFO.

Returns

None

Parameters

Parameter Datatype Default Value Description
message string None The message to write.
[edit]

LogDebug 

ClientAPI.LogDebug(message)

Writes message to the client log file, MultiverseClient.log. This method will log with a log level of DEBUG.

Returns

None

Parameters

Parameter Datatype Default Value Description
message string None The message to write.


[edit]

LogError 

ClientAPI.LogError(message)

Writes message to the client log file, MultiverseClient.log. This method will log with a log level of ERROR.

Returns

None

Parameters

Parameter Datatype Default Value Description
message string None The message to write.
[edit]

LogInfo 

ClientAPI.LogInfo(message)

Writes message to the client log file, MultiverseClient.log. This method will log with a log level of INFO.

Returns

None

Parameters

Parameter Datatype Default Value Description
message string None The message to write.


[edit]

LogWarn 

ClientAPI.LogWarn(message)

Writes message to the client log file, MultiverseClient.log. This method will log with a log level of WARN.

Returns

None

Parameters

Parameter Datatype Default Value Description
message string None The message to write.
[edit]

PickTerrain

This Client scripting API method, property, or object is deprecated. Although it still works in the current release, it may not work in future releases. Instead, use ClientAPI.World.PickTerrain(). 
loc = ClientAPI.PickTerrain(x, y)

Returns location in world space of the point that is displayed at the screen location specified by the x and y pixel coordinates.

Returns

Vector3

Parameters

Parameter Datatype Default Value Description
x float None The X coordinate of the screen location.
y float None The Y coordinate of the screen location.
[edit]

Random 

value = ClientAPI.Random(max)

Returns a random integer between 0 and max.

Returns

A random integer.

Parameters

Parameter Datatype Default Value Description
max int None The size of the range to select a random number from.
[edit]

RandomFloat 

value = ClientAPI.RandomFloat(max)

Returns a random floating point value between 0 and max.

Returns

A random floating point value.

Parameters

Parameter Datatype Default Value Description
max float None The size of the range to select a random number from.
[edit]

RegisterCommandHandler 

ClientAPI.RegisterCommandHandler(command, method)
NOTE: The RegisterCommandHandler method is no longer available in 1.1. Instead use MarsCommand.RegisterCommandHandler().

Register method with the command handler, so that when command is entered, the Client will call the associated method.

Returns

None

Parameters

Parameter Datatype Default Value Description
command string None Command for which to registering the handler (for example, 'hail').
method function(sender, target, args_str) None Method that will be called when the the command is invoked.
[edit]

RegisterEffect

This Client scripting API method, property, or object is deprecated. Although it still works in the current release, it may not work in future releases. Instead, use ClientAPI.World.RegisterEffect(). 
ClientAPI.RegisterEffect(effectName, effect)

Registers a class to handle the coordinated effect named effectName.

Returns

None

Parameters

Parameter Datatype Default Value Description
effectName string None The name of the effect.
effect Any coordinated effect class None The class for the given effect.
[edit]

RegisterEventHandler 

ClientAPI.RegisterEventHandler(eventName, eventHandler)

Registers a handler function for the named event.

Returns

None

Parameters

Parameter Datatype Default Value Description
eventName string None The name of the event. Valid events are:
  • FrameStarted
  • FrameEnded
  • PlayerInitialized
  • WorldConnect
  • WorldDisconnect
eventHandler function or method None The handler to call when the event is triggered.
NOTE: The events WorldInitialized, ObjectAdded, ObjectRemoved have been moved to World.RegisterEventHandler.
The TargetChanged event is no longer handled by the client, though world scripts such as MarsTarget will generate a UI event when the target changes.
[edit]

RemoveEventHandler 

ClientAPI.RemoveEventHandler(eventName, eventHandler)

Removes a handler function for the named event.

Returns

None

Parameters

Parameter Datatype Default Value Description
eventName string None The name of the event. Valid events are:
  • FrameStarted
  • FrameEnded
  • PlayerInitialized
  • WorldConnect
  • WorldDisconnect
eventHandler function or method None The handler to remove.
NOTE: The events WorldInitialized, ObjectAdded, and ObjectRemoved have been moved to World.RemoveEventHandler.
The TargetChanged event is no longer handled by the client, though world scripts such as MarsTarget will generate a UI event when the target changes.
[edit]

ReleasePlayerCamera 

ClientAPI.ReleasePlayerCamera()

Informs the client that a script is done moving the camera, so that the client can resume updating the camera location and orientation.

Returns

None

Parameters

None

[edit]

SetClientParameter 

status = ClientAPI.SetClientParameter(parameterName, val)

Sets a client parameter, and returns whether a matching parameter was found.

Returns

bool

Parameters

Parameter Datatype Default Value Description
parameterName string None The name of the parameter for which we are setting the value (e.g. 'Camera.PlayerVisible').
val string None The value to set as the new value of the parameter.
[edit]

SetMaterialScheme 

ClientAPI.SetMaterialScheme(schemeName)

Sets the current material scheme.

Returns

None

Parameters

Parameter Datatype Default Value Description
schemeName string None The name of the scheme to use.
[edit]

SetProfileMarker 

ClientAPI.SetProfileMarker( message, color)

Inserts a marker in the profile log when running the PIX graphics profiling tool in the Microsoft DirectX SDK. You can use this marker to trigger actions in PIX.

Returns

None

Parameters

Parameter Datatype Default Value Description
message string None The name of the marker.
color ClientAPI.ColorEx ClientAPI.ColorEx.Red The color that some applications may use to display this marker in their logs. PIX currently ignores this color.
[edit]

SetTextureNameOverride 

ClientAPI.SetTextureNameOverride(overrideName)

Enables a mechanism to access alternate textures. For example, lets say that your world has both high and low resolution textures, and you want to use one or the other based on the amount of graphics memory on the client system. When the texture name override is set, the engine will first look for the overridden name, and if it doesn't exist, it will load the texture with the normal name. The filename it looks for in the override case is the original base filename (not including file extension), followed by an underscore, the overrideName string, and finally the file extension. So if the overrideName is "LOWRES", and the engine wants to load "bricks.dds", it will first look for "bricks_LOWRES.dds", and if that texture is not present, it will look for "bricks.dds".

Here is an example that checks for low video memory and system memory, and if either exists, it uses the LOWRES version of the textures: 

# Use low res textures if we have less than 100MB video card memory 
#  or 700MB of system memory.
if ClientAPI.HardwareCaps.VideoMemorySize < 100 or ClientAPI.HardwareCaps.SystemMemorySize < 700:
    ClientAPI.SetTextureNameOverride("LOWRES")
    ClientAPI.Write("Using Low Resolution Textures")

NOTE - This code should be executed before any textures have been loaded. It is best to put code like this at the beginning of Startup.py.

Returns

None

Parameters

Parameter Datatype Default Value Description
overrideName string None The override name to use to find alternate assets.
[edit]

TakeScreenshot 

 ClientAPI.TakeScreenshot()

Captures the current contents of the screen and saves them in an image.

Returns

None

Parameters

None

[edit]

ToggleBoundingBoxes 

 ClientAPI.ToggleBoundingBoxes()

Toggle whether or not the bounding boxes around objects are drawn.

Returns

None

Parameters

None

[edit]

ToggleRenderCollisionVolumes 

ClientAPI.ToggleRenderCollisionVolumes()

Toggle whether or not the collision primitives are drawn. There are three states for this toggle:

  • All off
  • Static collision volumes on
  • Both static and dynamic collision volumes on

Returns

None

Parameters

None

[edit]

ToggleRenderMode 

ClientAPI.ToggleRenderMode()

Toggles how objects are rendered. There are three states for this toggle:

  • Standard
  • Wireframe
  • Point - this will not look correct on all video cards

Returns

None

Parameters

None

[edit]

ToggleTexture 

ClientAPI.ToggleTexture()

Toggles how textures are filtered. There are three states for this toggle:

  • Bilinear
  • Trilinear
  • Anisotropic

Returns

None

Parameters

None

[edit]

Write 

ClientAPI.Write(message)

Writes message to the client log file, MultiverseClient.log, and the in game chat window.

Returns

None

Parameters

Parameter Datatype Default Value Description
message string None The message to write.
[edit]

Properties

The ClientAPI module has the following properties:

Property Description
ClientAPI.AmbientLight A ColorEx value that enables configuration of the ambient light color.
ClientAPI.FogConfig An instance of the FogConfig class that enables configuration of fog in the client.
ClientAPI.HardwareCaps An instance of the HardwareCaps class that describes the capabilities of the graphics hardware.
ClientAPI.InputHandler Either an instance of GuiInputHandler (used during character creation/selection) or DefaultInputHandler (used thereafter) for sending messages to the server.
ClientAPI.MovieManager.Instance The singleton MovieManager object used to work with and load videos. See Displaying In-World Video and Web Pages.
ClientAPI.Network An instance of the Network class that enables sending messages to the server.
ClientAPI.OceanConfig An instance of the OceanConfig class that enables configuration of the ocean generated by the client.
ClientAPI.RootSceneNode The SceneNode at the root of the scene graph.
ClientAPI.ShadowConfig An instance of the ShadowConfig class that enables configuration of shadow display in the client.
[edit]

Events

The client has an event mechanism with the following events:

To create an event handler, use the ClientAPI.RegisterEventHandler() method and specify the event.

[edit]

FrameEnded

This event is triggered after the rendering of each frame. 

frameEndedHandler(sender, args)

Parameters

Parameter Datatype Description
sender object This parameter is not used.
args object This parameter is not used.
[edit]

FrameStarted

This event is triggered before the rendering of each frame. 

frameStartedHandler(sender, args)

Parameters

Parameter Datatype Description
sender object This parameter is not used.
args object This parameter is not used.


[edit]

ObjectAdded

This event is triggered when a WorldObject is created. 

objectAddedHandler(worldObj)

Parameters

Parameter Datatype Description
worldObj WorldObject The object that has been created.
[edit]

ObjectRemoved

This event is triggered when a WorldObject is removed. 

objectRemovedHandler(worldObj)

Parameters

Parameter Datatype Description
worldObj WorldObject The object that has been removed.
[edit]

TargetChanged

This event is triggered when the current target changes. 

targetChangedHandler(worldObj)
NOTE: The TargetChanged event is no longer available in 1.1. Similar functionality is available using UI events generated by the world script module MarsTarget.

Parameters

Parameter Datatype Description
worldObj WorldObject The new target object.
[edit]

WorldInitialized

This event is triggered when the world is initialized, which occurs when the client processes the message from the server that loads the world terrain. 

worldInitializedHandler(sender, args)

Parameters

Parameter Datatype Description
sender object This parameter is not used.
args object This parameter is not used.
Retrieved from "http://update.multiverse.net/wiki/index.php/Client_Scripting_API_-_ClientAPI"
Personal tools