3D actor object

The 3D actor object allows you to access the properties of your 3D actors. 3D actor objects are created by loading an actor definition file using the Game.LoadActor3D or Scene.LoadActor3D methods.


Methods

Actions
GoTo Makes the actor walk to a given point.
GoToObject Makes the actor walk to a specified entity.
GoTo3D Makes the actor walk to a given point in 3D space.
TurnTo Makes actor turn to the given direction or to a given object.
TurnToAngle Makes actor turn to the given angle.
IsWalking Queries whether the actor is currently walking.
PlayAnim Plays an animation.
PlayAnimChannel Plays an animation in a specified channel.
StopAnim Stops a currently playing animation.
StopAnimChannel Stops a currently playing animation in the specified channel.
IsAnimPlaying Checks whether the actor is currently playing an animation
IsAnimChannelPlaying Checks whether the actor is currently playing an animation in a specified channel
SetAnimTransitionTime Sets a transition time for an animation pair
GetAnimTransitionTime Queries a transition time for an animation pair
SkipTo3D Moves the actor to a specified point in 3D space
SetTexture Assigns a new texture to a specified material
SetTheoraTexture Assigns a Theora video as a texture to a specified material
SetEffect Assigns an advanced material defined by effect file to a specified material
RemoveEffect Removed an advanced material defined by effect file from a specified material
SetEffectParam Sets a parameter of an effect applied to a material
SetEffectParamVector Sets a 4D vector parameter of an effect applied to a material
SetEffectParamColor Sets a color parameter of an effect applied to a material
GetBonePosition2D Returns current position of a specified bone in screen coordinates
GetBonePosition3D Returns current position of a specified bone in world coordinates
AddIgnoredLight Adds a light to the list of lights that shouldn't affect the actor
RemoveIgnoredLight Removes a light from the list of lights that shouldn't affect the actor
Direct control
DirectWalk Makes the character walk forward.
DirectWalkBack Makes the character walk backwards.
DirectWalkStop Stops character from walking.
DirectTurnLeft Makes the character turn counter-clockwise.
DirectTurnRight Makes the character turn clockwise.
DirectTurnStop Stops character from turning.
Shadow related functions
SetShadowImage Sets and image to be used as a simple shadow for this actor
GetShadowImage Gets the currently assigned image to be used as a simple shadow for this actor
SetLightPosition Sets the position of a light to project a real-time shadow
Attachment functions
AddAttachment Load a new model from a file and attaches it to a specified bone of this actor
RemoveAttachment Permanently removes a specified attachment from this actor
GetAttachment Gets a reference to a specified attachment object
Animation management
MergeAnims Loads animations from X file
UnloadAnim Unload specified named animation from memory
Mesh related functions (deprecated)
HideMesh Hides a specified part (mesh) of this actor
ShowMesh Shows a specified part (mesh) of this actor
AddMesh Load a new model from a file and attaches it to a specified bone of this actor
RemoveMesh Permanently removes a specified mesh from this actor
Item functions
TakeItem Adds an item into the inventory.
DropItem Removes an item from the inventory.
GetItem Queries an inventory item.
HasItem Queries whether a given item is in inventory of any of this object.
Cursor functions
SetCursor Sets the standard cursor.
GetCursor Returns the filename of the cursor sprite (or null if no cursor is set)
GetCursorObject Returns a reference to the cursor sprite (or null if no cursor is set)
RemoveCursor Removes the standard cursor.
HasCursor Queries whether the standard cursor is set.
Script functions
AttachScript Executes a script file and attaches it to the object.
DetachScript Terminates a specified script file and detaches it from an object.
IsScriptRunning Queries whether a specified script file is running and attached to an object.
CanHandleMethod Queries whether the object supports a method of a specified name.
Sound functions
PlaySound Plays a sound. If the filename is omitted, the currently assigned sound is played (if any).
PlaySoundEvent Plays a sound and triggers an event when the sound is over. If the filename is omitted, the currently assigned sound is played (if any).
StopSound Stops the currently playing sound (if any).
PauseSound Pauses the currently playing sound.
ResumeSound Resumes a paused sound playback.
IsSoundPlaying Queries whether a sound playback is in progress.
SetSoundPosition Sets the sound's current playing position.
GetSoundPosition Queries the sound's current playing position
SetSoundVolume Sets a volume of the currently playing sound.
GetSoundVolume Gets a volume of the currently playing sound.
LoadSound Initializes a sound from file and makes it ready to be played.
Sound effects functions
SoundFXNone Removes any sound effect currently assigned to this object.
SoundFXEcho Assigns an echo effect to the sounds played by this object.
SoundFXReverb Assigns a reverb effect to the sounds played by this object.
Event functions
ApplyEvent Applies a named event to the object.
CanHandleEvent Queries whether the object has an event handler for a specified event.
Miscelaneous functions
SkipTo Moves an object to a specified location.
Reset Cancels the action the object was currently performing (like talking, walking etc.).
IsTalking Queries whether the object is currently talking.
StopTalking Cancels object's talking.
Talk Makes the object talk.
StickToRegion Forces this actor/entity to act like it's inside a given region
SetFont Sets font of this object.
GetFont Gets a font assigned to this object.
Particle functions
CreateParticleEmitter Initializes the particle emitter attached to this object.
DeleteParticleEmitter Deletes the particle emitter attached to this object.
CreateParticleEmitterBone Initializes the particle emitter and attaches it to a specified bone.

Attributes

Type (read only) Returns always "actor3d"
Direction The direction the actor is currently facing
DirectionAngle The angle the actor is currently facing, in degrees
Active Specifies whether the object is visible on screen
IgnoreItems Specifies whether the object appears to be non-interactive when an inventory item is used on it
SubtitlesPosRelative Specifies whether the SubtitlesPosX and SubtitlesPosY attributes are relative to default position, or absolute screen coordinates
SubtitlesPosX The X position of speech subtitles (either relative to speaker's position or absolute screen coordinates)
SubtitlesPosY The Y position of speech subtitles (either relative to speaker's position or absolute screen coordinates)
SubtitlesWidth Width of speech subtitles. Set to zero to restore the default behavior.
SubtitlesPosXCenter Specifies if the SubtitlesPosX attribute affects the center of the subtitle or its left side.
ParticleEmitter (read only) Returns the reference to the particle emitter object attached to this object, or null if the emitter haven't been initialized yet
NumAttachments (read only) Returns the number of entities attached to this object.
Name The internal name of the object.
Caption The caption of the object.
AccCaption A special caption of the object used for accessibility purposes.
X The X position of the object.
Y The Y position of the object.
Height (read only) Returns the current height of the object. In case of actors and entities the scaling is taken into account.
Filename (read only) Returns the filename.
Ready (read only) Returns whether the object isn't currently performing any action.
Interactive Specifies whether the object recieves user input.
SoundPanning Specifies whether the sounds played by this object are automatically panned depending on object's position on screen.
NonIntMouseEvents Specifies if the object can receive the MouseEntry and MouseLeave events even if the game is in non-interactive mode.
Scale The scale of this character in percent. The scale affects both the character model and its shadow.
PosX The 3D X coordinate of the actor's current position
PosY The 3D Y coordinate of the actor's current position
PosZ The 3D Z coordinate of the actor's current position
Velocity The movement velocity to be used for walking
AngularVelocity The turning velocity to be used for turning
ShadowType Specifies the shadow detail level to be used for this actor (0..none, 1..simple, 2..flat, 3..stencil shadows)
ShadowColor The RGBA color of the real-time shadow cast by this character
Shadow Specified if this character casts shadow (obsolete, use ShadowType)
SimpleShadow Specifies if simple shadow is used instead of real-time one (obsolete, use ShadowType)
DrawBackfaces Specifies whether the 3D model should display also polygons facing away from the camera.
TalkAnimName The name of an animation sequence to be used for talking
WalkAnimName The name of an animation sequence to be used for walking
IdleAnimName The name of an animation sequence to be used for standing still
TurnLeftAnimName The name of an animation sequence to be used for turning left (counter clockwise)
TurnRightAnimName The name of an animation sequence to be used for turning right (clockwise)
TalkAnimChannel The animation channel to be used for playing talking animations.
GoToTolerance Specifies the shortest distance between the actor's current position and its GoTo target (in pixels); If the distance is shorter than this value, GoTo command is ignored.
AnimTransitionTime Specifies the time taken to smoothly transition between two animations (in milliseconds)
AnimStopTransitionTime Specifies the time taken to smoothly transition back to basic pose after an animation finishes (in milliseconds)
DropToFloor Specifies whether the actor is always standing on the ground, no matter what Y coordinate is assigned to it.
AmbientLightColor The color of the scene ambient light, which only affects this actor (overrides scene ambient light color).

Low level events

MouseEntry The mouse pointer has been just moved over the object.
MouseLeave The mouse pointer has been just moved away from the object.

GoTo(X, Y)
GoToAsync(X, Y)

Makes the actor walk to a given point.

Parameters

X
The X coordinate of the target walking point
Y
The Y coordinate of the target walking point

Remarks

The GoTo method blocks the script execution until the walking is over, while the GoToAsync method returns immediately.


GoToObject(Entity)
GoToObjectAsync(Entity)

Makes the actor walk to a specified entity.

Parameters

Entity
The entity object the actor should walk and turn to

Remarks

This method utilizes the WalkToX, WalkToY and WalkToDirection properties of the target entity. They can be set directly in SceneEdit.


GoTo3D(X, Y, Z)
GoTo3DAsync(X, Y, Z)

Makes the actor walk to a given point in 3D space.

Parameters

X
The X coordinate of the target walking point
Y
The Y coordinate of the target walking point

Remarks

The GoTo3D method blocks the script execution until the walking is over, while the GoTo3DAsync method returns immediately. Unlike the standard GoTo method, this method doesn't project the target point from screen position, but rather uses the "raw" 3D point within scene geometry as a target point.


TurnTo(Direction)
TurnTo(Object)
TurnToAsync(Direction)
TurnToAsync(Object)

Makes actor turn to the given direction or to a given object.

Parameters

Direction
The direction to turn to
Object
The object to turn to

Remarks

The TurnTo method blocks the script execution until the turning is over, while the TurnToAsync method returns immediately. The direction can be one of the following constants: DI_UP, DI_UPRIGHT, DI_RIGHT, DI_DOWNRIGHT, DI_DOWN, DI_DOWNLEFT, DI_LEFT or DI_UPLEFT (those equal to numbers 0 to 7).


TurnToAngle(Angle)
TurnToAngleAsync(Angle)

Makes actor turn to the given angle.

Parameters

Angle
The angle to turn to, in degrees

Remarks

The TurnToAngle method blocks the script execution until the turning is over, while the TurnToAngleAsync method returns immediately.


IsWalking()

Queries whether the actor is currently walking.

Return value

Returns true if the actor is walking.


PlayAnim(AnimName)
PlayAnimAsync(AnimName)

Plays an animation.

Parameters

AnimName
The name of the animation sequence to be played

Return value

Returns true if the animation has been played successfuly.

Remarks

The PlayAnim method blocks the script execution until the animation is over, while the PlayAnimAsync method returns immediately. PlayAnim is equivalent to PlayAnimChannel with channel set to zero.


PlayAnimChannel(Channel, AnimName)
PlayAnimChannelAsync(Channel, AnimName)

Plays an animation in a specified channel.

Parameters

Channel
The channel to be used by this animation (0 - 9)
AnimName
The name of the animation sequence to be played

Return value

Returns true if the animation has been played successfuly.

Remarks

The PlayAnimChannel method blocks the script execution until the animation is over, while the PlayAnimChannelAsync method returns immediately.


StopAnim(TransitionTime)

Stops a currently playing animation.

Parameters

TransitionTime
The transition time to smoothly switch back to basic pose, in milliseconds (optional, default=0)

Return value

Returns true if the animation has been stopped successfuly.


StopAnimChannel(Channel)

Stops a currently playing animation in the specified channel.

Parameters

Channel
The channel in which the animation should be stopped (0 - 9)
TransitionTime
The transition time to smoothly switch back to basic pose, in milliseconds (optional, default=0)

Return value

Returns true if the animation has been stopped successfuly.


IsAnimPlaying(AnimName)

Checks whether the actor is currently playing an animation

Parameters

AnimName
Optional animation name to be queried

Return value

Returns true if the actor is playing an animation.

Remarks

If you don't specify an animation name, this method checks if any animaton is playing. Otherwise it checks if the specified animation is playing.


IsAnimChannelPlaying(Channel, AnimName)

Checks whether the actor is currently playing an animation in a specified channel

Parameters

Channel
The channel in which the animation should be queried (0 - 9)
AnimName
Optional animation name to be queried

Return value

Returns true if the actor is playing an animation in a specified channel.

Remarks

If you don't specify an animation name, this method checks if any animaton is playing. Otherwise it checks if the specified animation is playing.


SetAnimTransitionTime(AnimFrom, AnimTo, Time)

Sets a transition time for an animation pair

Parameters

AnimFrom
The original animation
AnimTo
The new animation
Time
The transition time

Return value

Returns true if the method succeeded.

Remarks

For example, if you want to set the transition from walking to idle animation to 1 second, you'd call: actor.SetAnimTransitionTime("walk", "idle", 1000); Specify a negative Time value to restore the default transition time.


GetAnimTransitionTime(AnimFrom, AnimTo)

Queries a transition time for an animation pair

Parameters

AnimFrom
The original animation
AnimTo
The new animation

Return value

Returns the transition time for the specified animation pair, or a negative value if no transition time is defined.


SkipTo3D(X, Y, Z)

Moves the actor to a specified point in 3D space

Parameters

X
The X coordinate
Y
The Y coordinate
Z
The Z coordinate

SetTexture(MaterialName, TextureFilename)

Assigns a new texture to a specified material

Parameters

Material
The material whose texture should be set
TextureFilename
The filename of a new texture

Remarks

MaterialName defaults to the name of the original texture assigned to the model, without extension. For example, if the model uses texture called "path\some_texture.png", the material will be called "some_texture". TextureFilename can be either a static image or WME sprite.


SetTheoraTexture(MaterialName, VideoFilename)

Assigns a Theora video as a texture to a specified material

Parameters

Material
The material whose texture should be set
VideoFilename
The filename of a Theora video to be used as texture

Remarks

MaterialName defaults to the name of the original texture assigned to the model, without extension. For example, if the model uses texture called "path\some_texture.png", the material will be called "some_texture". The Theora video dimensions must be powers of two (2, 4, 8, 16, 32...) and the video is always looping until it's replaced by other texture.


SetEffect(MaterialName, EffectFilename)

Assigns an advanced material defined by effect file to a specified material

Parameters

Material
The material to which the effect is to be assigned
EffectFilename
The filename of an effect file

Remarks

MaterialName defaults to the name of the original texture assigned to the model, without extension. For example, if the model uses texture called "path\some_texture.png", the material will be called "some_texture".


RemoveEffect(MaterialName)

Removed an advanced material defined by effect file from a specified material

Parameters

Material
The material from which the effect is to be removed

Remarks

MaterialName defaults to the name of the original texture assigned to the model, without extension. For example, if the model uses texture called "path\some_texture.png", the material will be called "some_texture".


SetEffectParam(MaterialName, ParamName, Value)

Sets a parameter of an effect applied to a material

Parameters

Material
The material to which the effect parameter is to be assigned
ParamName
The name of the parameter to set
Value
The value to be assigned to the parameter

Remarks

The value can contain one of the following types: string, logical value, integer number or floating point number.


SetEffectParamVector(MaterialName, ParamName, X, Y, Z, W)

Sets a 4D vector parameter of an effect applied to a material

Parameters

Material
The material to which the effect parameter is to be assigned
ParamName
The name of the parameter to set
X
The X coordinate of a vector
Y
The Y coordinate of a vector
Z
The Z coordinate of a vector
W
The W coordinate of a vector

SetEffectParamColor(MaterialName, ParamName, Color)

Sets a color parameter of an effect applied to a material

Parameters

Material
The material to which the effect parameter is to be assigned
ParamName
The name of the parameter to set
Color
The color to be assigned to parameter

Remarks

The Color parameter should contain a packed RGBA color value created using the MakeRGBA() function. Internally the color is converted to a 4D vector.


GetBonePosition2D(BoneName)

Returns current position of a specified bone in screen coordinates

Parameters

BoneName
The name of the bone to be queried

Return value

Returns an object providing two properties, X and Y.


GetBonePosition3D(BoneName)

Returns current position of a specified bone in world coordinates

Parameters

BoneName
The name of the bone to be queried

Return value

Returns an object providing three properties, X, Y and Z.


AddIgnoredLight(LightName)

Adds a light to the list of lights that shouldn't affect the actor

Parameters

LightName
The name of the light that will not affect the actor

Return value

Returns true if the method succeeded.

Remarks

The light name is case-insensitive.


RemoveIgnoredLight(LightName)

Removes a light from the list of lights that shouldn't affect the actor

Parameters

LightName
The name of the light to be removed from ignore list

Return value

Returns true if the method succeeded.

Remarks

The light name is case-insensitive.


DirectWalk(Velocity, Animation)

Makes the character walk forward.

Parameters

Velocity
The walking velocity to be used (optional, defaults to standard velocity)
Animation
The animation to be used (optional, defaults to standard animation)

DirectWalkBack(Velocity, Animation)

Makes the character walk backwards.

Parameters

Velocity
The walking velocity to be used (optional, defaults to standard velocity)
Animation
The animation to be used (optional, defaults to standard animation)

DirectWalkStop()

Stops character from walking.


DirectTurnLeft(Velocity, Animation)

Makes the character turn counter-clockwise.

Parameters

Velocity
The turning velocity to be used (optional, defaults to standard velocity)
Animation
The animation to be used (optional, defaults to standard animation)

DirectTurnRight(Velocity, Animation)

Makes the character turn clockwise.

Parameters

Velocity
The turning velocity to be used (optional, defaults to standard velocity)
Animation
The animation to be used (optional, defaults to standard animation)

DirectTurnStop()

Stops character from turning.


SetShadowImage(Filename)

Sets and image to be used as a simple shadow for this actor

Parameters

Filename
The filename of an image to be used

Return value

Returns true if the image has been successfuly set.


GetShadowImage()

Gets the currently assigned image to be used as a simple shadow for this actor

Return value

Returns the filename of currently assigned shadow image or null if no image is set.


SetLightPosition(X, Y, Z)

Sets the position of a light to project a real-time shadow

Parameters

X
The X coordinate of the light
Y
The Y coordinate of the light
Z
The Z coordinate of the light

Remarks

The light position is relative to actor's position.


AddAttachment(Filename, AttachmentName, ParentBone)

Load a new model from a file and attaches it to a specified bone of this actor

Parameters

Filename
Filename of the model file to be loaded (X file)
AttachmentName
The name of the attachment to be loaded
ParentBone
The name of the bone the loaded mesh will be attached to

Return value

Returns true if the attachment has been successfuly loaded and attached.


RemoveAttachment(AttachmentName)

Permanently removes a specified attachment from this actor

Parameters

AttachmentName
The attachment to be removed

Return value

Returns true if the attachment has been successfuly removed.


GetAttachment(AttachmentName)

Gets a reference to a specified attachment object

Parameters

AttachmentName
The attachment to be queried

Return value

Returns a reference to an attachment object or null if there's no attachment with a specified name.


MergeAnims(ModelName)

Loads animations from X file

Parameters

ModelName
The name of an X model whose animations should be loaded

Return value

Returns true if the animations have been successfuly merged.


UnloadAnim(AnimationName)

Unload specified named animation from memory

Parameters

AnimationName
The name of the animation to be unloaded

Return value

Returns true if the animation has been successfuly removed.


HideMesh(MeshName)

Hides a specified part (mesh) of this actor

Parameters

MeshName
The mesh to be hidden

Return value

Returns true if the mesh has been successfuly hidden.

Remarks

This method is DEPRECATED and not supported by .X models.


ShowMesh(MeshName)

Shows a specified part (mesh) of this actor

Parameters

MeshName
The mesh to be shown

Return value

Returns true if the mesh has been successfuly shown.

Remarks

This method is DEPRECATED and not supported by .X models.


AddMesh(Filename, MeshName, ParentBone)

Load a new model from a file and attaches it to a specified bone of this actor

Parameters

Filename
Filename of the model file to be loaded (MS3D file)
MeshName
The name of the mesh to be loaded
ParentBone
The name of the bone (joint) the loaded mesh will be attached to

Return value

Returns true if the mesh has been successfuly loaded and attached.

Remarks

This method is DEPRECATED and not supported by .X models.


RemoveMesh(MeshName)

Permanently removes a specified mesh from this actor

Parameters

MeshName
The mesh to be removed

Return value

Returns true if the mesh has been successfuly removed.

Remarks

This method is DEPRECATED and not supported by .X models.


TakeItem(ItemName, InsertAfter)

Adds an item into the inventory.

Parameters

ItemName
A name of the item to be added to object's inventory.
InsertAfter
A name of the item which the new item should be inserted after (optional).

DropItem(ItemName)

Removes an item from the inventory.

Parameters

ItemName
A name of the item to be removed from object's inventory.

GetItem(ItemIndex)
GetItem(ItemName)

Queries an inventory item.

Parameters

ItemIndex
An index of a taken item to be queried.
ItemName
A name of an inventory item to be queried.

Return value

A reference to the item object of a given name or at a given index in the inventory.


HasItem(ItemName)
HasItem(ItemObject)

Queries whether a given item is in inventory of any of this object.

Parameters

ItemName
A name of the item to be queried.
ItemObject
Reference to the item object to be queried.

Return value

If the specified item is in the inventory of this object, the return value is true.

Remarks

Note that this method only searches the current object, use the Game.IsItemTaken() method if you want to search all game objects.


SetCursor(Filename)

Sets the standard cursor.

Parameters

Filename
Filename of a sprite file to be used as a cursor pointer.

Return value

Returns true if the cursor has been set succesfuly.


GetCursor()

Returns the filename of the cursor sprite (or null if no cursor is set)


GetCursorObject()

Returns a reference to the cursor sprite (or null if no cursor is set)


RemoveCursor()

Removes the standard cursor.


HasCursor()

Queries whether the standard cursor is set.

Return value

Returns true if the object has a custom mouse pointer assigned.


AttachScript(Filename)

Executes a script file and attaches it to the object.

Parameters

Filename
The filename of the script file to be executed.

Return value

Returns true if the script has been executed succesfuly.

Remarks

Each WME object can have multiple scripts attached.


DetachScript(Filename, KillThreads)

Terminates a specified script file and detaches it from an object.

Parameters

Filename
The filename of the (running) script to be terminated and detached.
KillThreads
Specifies whether to terminate all running threads of this script (optional, default=false)

Return value

Returns true if the script has been detached succesfully.

Remarks

Script threads are currently executed event handlers and methods.


IsScriptRunning(Filename)

Queries whether a specified script file is running and attached to an object.

Parameters

Filename
The filename of the script to be queried.

Return value

Returns true if a specified script file is attached to an object.


CanHandleMethod(MethodName)

Queries whether the object supports a method of a specified name.

Parameters

MethodName
The name of the method to be checked.

Return value

Returns true if the object is able to handle the specified method.


PlaySound(Filename, Looping, LoopStart)
PlaySound(Looping, LoopStart)

Plays a sound. If the filename is omitted, the currently assigned sound is played (if any).

Parameters

Filename
The filename of the sound file to be played
Looping
Whether the sound should be looped (optional, default = false).
LoopStart
The point from which the sound restarts when looping, in milliseconds (optional, default=0).

Return value

If the method succeeds, the return value is true.


PlaySoundEvent(Filename, EventName)
PlaySoundEvent(EventName)

Plays a sound and triggers an event when the sound is over. If the filename is omitted, the currently assigned sound is played (if any).

Parameters

Filename
The filename of the sound file to be played
EventName
The name of the event to be triggered after the sound finishes.

Return value

If the method succeeds, the return value is true.


StopSound()

Stops the currently playing sound (if any).

Return value

If the method succeeds, the return value is true.


PauseSound()

Pauses the currently playing sound.

Return value

If the method succeeds, the return value is true.


ResumeSound()

Resumes a paused sound playback.

Return value

If the method succeeds, the return value is true.


IsSoundPlaying()

Queries whether a sound playback is in progress.

Return value

If the sound is playing, the return value is true.


SetSoundPosition(Time)

Sets the sound's current playing position.

Parameters

Time
A new playing position (in milliseconds)

Return value

If the method succeeds, the return value is true.


GetSoundPosition()

Queries the sound's current playing position

Return value

Returns the current playing position (in milliseconds).


SetSoundVolume(Volume)

Sets a volume of the currently playing sound.

Parameters

Volume
A new sound volume (in percent).

Return value

If the method succeeds, the return value is true.


GetSoundVolume()

Gets a volume of the currently playing sound.

Return value

Returns the volume of the currently playing sound (in percent).


LoadSound(Filename)

Initializes a sound from file and makes it ready to be played.

Parameters

Filename
The sound file to be loaded

Return value

If the method succeeds, the return value is true.

Remarks

Use this method to pre-cache a sound file. Initializing the sound takes some time and sometimes it's desirable to move all sound initialization to e.g. scene start so that the subsequent PlaySound calls don't slow the game down. That's what LoadSound is for. To play the pre-cached sound simply call PlaySound without specifying a filename, for example SomeObject.PlaySound(false);


SoundFXNone()

Removes any sound effect currently assigned to this object.


SoundFXEcho(WetDryMix, Feedback, LeftDelay, RightDelay)

Assigns an echo effect to the sounds played by this object.

Parameters

WetDryMix
Wet/Dry Mix, in percent (0 to 100)
Feedback
Feedback, in percent (0 to 100)
LeftDelay
Left delay, in milliseconds (1 to 2000)
RightDelay
Right delay, in milliseconds (1 to 2000)

Remarks

Example: actor.SoundFXEcho(50, 50);


SoundFXReverb(InGain, ReverbMix, ReverbTime, HighFreqRTRatio)

Assigns a reverb effect to the sounds played by this object.

Parameters

InGain
In gain, in dB (-96 to 0)
ReverbMix
Reverb mix, in dB (-96 to 0)
ReverbTime
Reverb time, in milliseconds (0.001 to 3000)
HighFreqRTRatio
HighFreq RT Ratio (0.001 to 0.999)

Remarks

Example: actor.SoundFXReverb(0, 0, 2000);


ApplyEvent(EventName)

Applies a named event to the object.

Parameters

EventName
A name of the event to be applied to the object.

Return value

Returns true it the event has been applied succesfuly.


CanHandleEvent(EventName)

Queries whether the object has an event handler for a specified event.

Parameters

EventName
The name of the event to be checked.

Return value

Returns true if the object is able to handle the specified event.


SkipTo(X, Y)

Moves an object to a specified location.

Parameters

X
Destination X coordinate.
Y
Destination Y coordinate.

Reset()

Cancels the action the object was currently performing (like talking, walking etc.).


IsTalking()

Queries whether the object is currently talking.

Return value

Returns true if the object is talking.


StopTalking()

Cancels object's talking.

Remarks

You can also use StopTalk() abbreviation.


Talk(Text, SoundFilename, Duration, TalkStances, TextAlignment)
TalkAsync(Text, SoundFilename, Duration, TalkStances, TextAlignment)

Makes the object talk.

Parameters

Text
A text to be used as a talk subtitle
SoundFilename
A filename of a sound file to be used (oprtional, default is no sound)
Duration
A subtitle duration in milliseconds (optional, default is 0)
TalkStances
A comma separated list of talk "stances" to be used for the talking (optional, default is random stances)
TextAlignment
A text alignment for the subtitle (0-left, 1-right, 2-center) (optional, default=2)

Remarks

Talk method blocks the script execution until the animation is over, while the TalkAsync method returns immediately. If the duration is set to zero, it's calculated automatically either from the sound file or from the length of the subtitle.


StickToRegion(Region)
StickToRegion(RegionName)

Forces this actor/entity to act like it's inside a given region

Parameters

Region
Reference to a scene region object
RegionName
Name of a scene region

Remarks

Use this method to "lock" a z-order value of an actor or an entity.


SetFont(Filename)

Sets font of this object.

Parameters

Filename
The name of the font to be set.

Return value

If the method succeeds, the return value is true.


GetFont()

Gets a font assigned to this object.

Return value

Returns the filename of currently assigned font.


CreateParticleEmitter(FollowOwner, OffsetX, OffsetY)

Initializes the particle emitter attached to this object.

Parameters

FollowOwner
Specifies whether the particle emitter inherits position of its owner object
OffsetX
If FollowOwner is true, this is the X offset to be added to owner's position when displaying particles
OffsetY
If FollowOwner is true, this is the Y offset to be added to owner's position when displaying particles

Return value

Returns the reference to the particle emitter object

Remarks

Once initialized with this method, the particle emitter object can be queried using the ParticleEmitter property.


DeleteParticleEmitter()

Deletes the particle emitter attached to this object.

Return value

Returns true if the method succeeded.


CreateParticleEmitterBone(BoneName, OffsetX, OffsetY, OffsetZ)

Initializes the particle emitter and attaches it to a specified bone.

Parameters

BoneName
The name of the bone the particle emitter is attached to
OffsetX
The X offset to be added to bone's 3D position when displaying particles
OffsetY
The Y offset to be added to bone's 3D position when displaying particles
OffsetZ
The Z offset to be added to bone's 3D position when displaying particles

Return value

Returns the reference to the particle emitter object

Remarks

Once initialized with this method, the particle emitter object can be queried using the ParticleEmitter property.