Entity object

The Entity object allows you to access the properties of your entities. Entity objects are created by loading an entity definition file using the Game.LoadEntity or Scene.LoadEntity methods. Entities which are part of the scene layout can be queried by using the Scene.GetNode method.


Methods

Actions
SetSprite Sets entity's default sprite.
SetTalkSprite Sets entity's talk sprite.
AddTalkSprite Adds entity's talk sprite.
RemoveTalkSprite Removes a sprite from the list of talk sprites.
GetSprite Queries a default sprite of this entity.
GetSpriteObject Queries a default sprite of this entity.
CreateRegion Creates a region for this entity.
DeleteRegion Removes a region from this entity.
Video playback
PlayTheora Plays a video in Theora format
StopTheora Stops the Theora video playback
IsTheoraPlaying Queries whether the entity is currently playing a Theora video
PauseTheora Pauses the Theora video playback
ResumeTheora Resumes a paused Theora video playback
IsTheoraPaused Queries whether the entity is currently playing a Theora video and the playback is paused
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.
Miscelaneous functions
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.
PlayAnim Plays an animation.
ForceTalkAnim Force a special animation to be used for a subsequent Talk call.
AddAttachment Adds an attached entity to this object.
RemoveAttachment Removes an attached entity from this object.
GetAttachment Gets a reference to an attached entity object.
SkipTo Moves an object to a specified location.
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.

Attributes

Type (read only) Returns always "entity"
Subtype (read only) Returns either "normal" or "sound" depending on entity type
Item Specifies a name of an inventory item which controls the activity of this entity
SaveState Specifies if the scene entity remembers its state after the player leaves the scene
WalkToX The default postition the actor should walk to using the GoToObject method (X)
WalkToY The default postition the actor should walk to using the GoToObject method (Y)
WalkToDirection The default direction the actor turn to after walking to this entity using the GoToObject method.
Region (read only) Returns a reference to the region object assigned to this entity, or null if no region is assigned.
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.
Movable Specifies whether the object can be moved by its sprites (in case the sprite frames have a "move" property set).
Scalable Specifies whether the object is affected by scene's scaling levels.
Rotatable Specifies whether the object is affected by scene's rotation levels.
Colorable Specifies whether the object is affected by scene's color regions.
AlphaColor Specifies an RGBA color of this object (overrides scene coloring); set to 0 to reset default behavior.
BlendMode Specifies how the object's image is blended with the background colors; 0...normal mode, 1...additive blending, 2...subtractive blending
Scale Specifies a scale of this object (overrides scene scaling); set to null to reset default behavior.
ScaleX Specifies horizontal scale of this object; set to null to reset default behavior.
ScaleY Specifies vertical scale of this object; set to null to reset default behavior.
RelativeScale Specifies a scale amount to be added to the default scene scale.
Rotate Specifies rotation of this object (in degrees); overrides scene rotation; set to null to reset default behavior; not available in compatibility mode
RelativeRotate Specifies a rotation amount to be added to the default scene rotation.

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.

SetSprite(Filename)

Sets entity's default sprite.

Parameters

Filename
The filename of the sprite file to be used as a default sprite.

Return value

If the method succeeds, the return value is true.


SetTalkSprite(Filename, Extended)

Sets entity's talk sprite.

Parameters

Filename
The filename of the sprite file to be used as a talk sprite.
Extended
Should this sprite be used for explicit talk stances only (optional, default=false).

Return value

If the method succeeds, the return value is true.


AddTalkSprite(Filename, Extended)

Adds entity's talk sprite.

Parameters

Filename
The filename of the sprite file to be added to the list of talk sprites.
Extended
Should this sprite be used for explicit talk stances only (optional, default=false).

Return value

If the method succeeds, the return value is true.


RemoveTalkSprite(Filename)

Removes a sprite from the list of talk sprites.

Parameters

Filename
The filename of the sprite file to be removed.

Return value

If the method succeeds, the return value is true.


GetSprite()

Queries a default sprite of this entity.

Return value

Returns filename of the currently assigned sprite.


GetSpriteObject()

Queries a default sprite of this entity.

Return value

Returns a reference to the currently assigned sprite object.


CreateRegion()

Creates a region for this entity.

Return value

Returns the reference to the region object or null if the creation failed.

Remarks

If the entity already has a region assigned, it's NOT recreated and this method returns the original region.


DeleteRegion()

Removes a region from this entity.

Return value

Returns true if the method succeeded.


PlayTheora(Filename, Looping, AlphaImage, StartTime)

Plays a video in Theora format

Parameters

Filename
The Ogg Theora file to be played
Looping
Specifies whether the video should loop (optional, default=false)
AlphaImage
Specifies the image to be used for an alpha channel underlying the video playback (optional)
StartTime
Specifies the time point from which the video playback starts, in milliseconds (optional)

StopTheora()

Stops the Theora video playback


IsTheoraPlaying()

Queries whether the entity is currently playing a Theora video

Return value

Returns true if video playback is in progress


PauseTheora()

Pauses the Theora video playback


ResumeTheora()

Resumes a paused Theora video playback


IsTheoraPaused()

Queries whether the entity is currently playing a Theora video and the playback is paused

Return value

Returns true if video playback is paused


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.


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.


PlayAnim(Filename)
PlayAnimAsync(Filename)

Plays an animation.

Parameters

Filename
A filename of a sprite file 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. For actors, you can also specify an animation set name instead of filename.


ForceTalkAnim(Filename)

Force a special animation to be used for a subsequent Talk call.

Parameters

Filename
A filename of the sprite file to be used as a talking animation

Remarks

This setting has only effect on one subsequent Talk() method call. After the talking is over, the talking animation is reset back to default.


AddAttachment(EntityFile, PreDisplay, OffsetX, OffsetY)

Adds an attached entity to this object.

Parameters

EntityFile
The filename of the entity to be attached.
PreDisplay
Specifies whether the attached entitiy is drawn below the object or on top of it (optional, default=true)
OffsetX
The X offset of the attachment relative to object's position
OffsetY
The Y offset of the attachment relative to object's position

Return value

Returns true is the attachment has been successfuly attached.

Remarks

This method is typically used for attaching a "blob" shadow image to an actor or an entity. The X and Y offset is scaled accordingly to object's current scale.


RemoveAttachment(AttachmentName)
RemoveAttachment(AttachmentIndex)

Removes an attached entity from this object.

Parameters

AttachmentName
The name of the entity to be detached
AttachmentIndex
The index of the attachment to be detached

Return value

Returns true if the attachment has been successfuly detached.


GetAttachment(AttachmentName)
GetAttachment(AttachmentIndex)

Gets a reference to an attached entity object.

Parameters

AttachmentName
The name of the attached entity to be queried
AttachmentIndex
The index of the attachment to be queried

Return value

Returns a reference to the attached entity or null if specified attachement cannot be found.


SkipTo(X, Y)

Moves an object to a specified location.

Parameters

X
Destination X coordinate.
Y
Destination Y coordinate.

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.