Scene object

The Scene object represents the currently loaded scene. There is always one and only Scene object available. It's accessible via the Game.Scene attribute. For the convenience the templates automatically store the scene object in a global variable named Scene.


Methods

Object manipulation
LoadActor Loads a new actor from a file.
LoadActor3D Loads a new 3D actor from a file.
LoadEntity Loads a new entity from a file.
UnloadObject Removes an object from memory.
Scrolling functions
SkipTo Sets the current scroll position to the given point / object.
ScrollTo Scrolls the scene to the given point / object.
Node querying functions
GetLayer Returns the given layer.
GetWaypointGroup Returns the given waypoint group.
GetNode Returns the given scene node (entity or region).
GetFreeNode Returns the given free scene node (entity or actor).
GetRegionAt Returns a scene region at a given position.
Scene querying functions
IsBlockedAt Queries whether the scene is blocked at a given point.
IsWalkableAt Queries whether the scene is walkable at a given point.
GetScaleAt Queries a scale factor at a given point of the scene.
GetRotationAt Queries a sprite rotation factor at a given point of the scene.
IsPointInViewport Queries whether a given point is lying within the current scene viewport.
Fading functions
FadeOut Fades the scene out to a specified color.
FadeIn Fades the scene in from a specified color.
GetFadeColor Gets the current fading color.
Dynamic object creation
CreateEntity Creates a new entity object.
DeleteEntity Destroys a entity object.
AddLayer Adds a new layer to the top of the scene
InsertLayer Inserts a new layer to the scene
DeleteLayer Permanently removes a scene layer
3D characters related
EnableNode3D Enables a 3D walkplane or blocked object
DisableNode3D Disables a 3D walkplane or blocked object
IsNode3DEnabled Checks whether a specified 3D walkplane or blocked object is enabled.
EnableLight Enables a 3D light within the scene
DisableLight Disables a 3D light within the scene
IsLightEnabled Checks whether a specified 3D light is enabled.
SetLightColor Changes the color of a 3D light
GetLightColor Queries the color of a 3D light
GetLightPosition Queries the position of a 3D light
GetLightName Queries the name of a specified 3D light
SetActiveCamera Switches a camera used to display 3D objects in scene
EnableFog Enables linear fog within the scene, which affects the 3D actors
DisableFog Disables fog within the scene.
Miscelaneous functions
SetViewport Sets scene viewport to specified values.

Attributes

Type (read only) Returns always "scene"
Name The internal name of the scene
Filename (read only) Returns the filename.
Ready (read only) Returns whether the scene is ready (the scrolling is over)
NumLayers (read only) Returns the number of layers
NumWaypointGroups (read only) Return the number of waypoint groups
MouseX (read only) Returns the current X position of the mouse cursor within the scene
MouseY (read only) Returns the current Y position of the mouse cursor within the scene
MainLayer (read only) Returns a reference to the scene's main layer
AutoScroll Specifies whether scene automatically scrolls to the Game.MainObject
IsScrolling (read only) Returns true if the scene is currently scrolling.
PersistentState Specifies whether the engine "remembers" the previous state of scene nodes when re-entering the scene
ScrollSpeedX Horizontal scrolling speed (in milliseconds, default=10)
ScrollSpeedY Vertical scrolling speed (in milliseconds, default=10)
ScrollPixelsX Horizontal scrolling shift (in pixels, default=1)
ScrollPixelsY Vertical scrolling shift (in pixels, default=1)
OffsetX Current horizontal scrolling offset of the scene
OffsetY Current vertical scrolling offset of the scene
Width Specifies the width of the main scene layer
Height Specifies the height of the main scene layer
NumFreeNodes (read only) Returns the number of free scene nodes
GeometryFile (read only) The filename of the geometry file assigned to scene or null if no geometry is assigned
ShowGeometry Specifies if the hidden scene geometry is displayed (for development purposes only)
MaxShadowType Specifies the maximum shadow detail to be used in this scene (0..none, 1..simple, 2..flat, 3..stencil shadows)
AmbientLightColor The color of the scene ambient light, which affects 3D actors
NumLights (read only) Returns the number of 3D lights defined by the hidden scene geometry.

Low level events

SceneShutdown Triggered before the scene is about to be destroyed. Event handler must not contain any blocking command, such as Sleep(), GoTo() etc.

LoadActor(Filename)

Loads a new actor from a file.

Parameters

Filename
The filename of the actor file to be loaded.

Return value

A reference to the new Actor object. If the method fails, the return value is null.

Remarks

Actors loaded using this method will be automatically unloaded when the game changes to another scene (as opposed to the Game.LoadActor method).


LoadActor3D(Filename)

Loads a new 3D actor from a file.

Parameters

Filename
The filename of the 3D actor file to be loaded.

Return value

A reference to the new 3D actor object. If the method fails, the return value is null.

Remarks

Actors loaded using this method will be automatically unloaded when the game changes to another scene (as opposed to the Game.LoadActor3D method).


LoadEntity(Filename)

Loads a new entity from a file.

Parameters

Filename
The filename of the entity file to be loaded.

Return value

A reference to the new Entity object. If the method fails, the return value is null.

Remarks

Entities loaded using this method will be automatically unloaded when the game changes to another scene (as opposed to the Game.LoadEntity method).


UnloadObject(Object)

Removes an object from memory.

Parameters

Object
The object to be removed from memory.

Remarks

If you load an object using the Scene.LoadActor or Scene.LoadEntity methods, you should unload those when you no longer need them to free memory. Otherwise those objects will be released automatically when the game changes to another scene.


SkipTo(X, Y)
SkipTo(Object)

Sets the current scroll position to the given point / object.

Parameters

X
New X coordinate for scroll position
Y
New Y coordinate for scroll position
Object
An object (actor/entity) to be used as a new scroll position

ScrollTo(X, Y)
ScrollTo(Object)
ScrollToAsync(X, Y)
ScrollToAsync(Object)

Scrolls the scene to the given point / object.

Parameters

X
X coordinate of the target scroll position
Y
Y coordinate of the target scroll position
Object
An object (actor/entity) to be used as a new target scroll position

Remarks

The Scene.AutoScroll attribute must be set to true for this method to work. ScrollTo method blocks the script execution until the scrolling is over, while the ScrollToAsync method returns immediately.


GetLayer(LayerIndex)
GetLayer(LayerName)

Returns the given layer.

Parameters

LayerIndex
An index of a layer to be returned
LayerName
A name of a layer to be returned

Return value

Returns a reference to the layer object at a given index/with a given name or returns null if there's no such layer.


GetWaypointGroup(WptGroupIndex)

Returns the given waypoint group.

Parameters

WptGroupIndex
An index of a waypoint group to be returned

Return value

Returns a reference to the waypoint group object at a given index or null if there's no such waypoint group.


GetNode(Name)

Returns the given scene node (entity or region).

Parameters

Name
The name of the scene node to be returned

Return value

Returns a reference to the scene node object with a given name or null if there's no such node.

Remarks

The scene nodes should have unique names for this method to work correctly.


GetFreeNode(Name)
GetFreeNode(Index)

Returns the given free scene node (entity or actor).

Parameters

Name
The name of the scene node to be returned
Index
The index of the scene node to be returned

Return value

Returns a reference to the scene node object with a given name/index or null if there's no such node.


GetRegionAt(X, Y, IncludeDecorations)

Returns a scene region at a given position.

Parameters

X
The X coordinate within the scene to be searched for regions
Y
The Y coordinate within the scene to be searched for regions
IncludeDecorations
Specifies whether the decoration regions should be searched too (optional, default=false)

Return value

Returns a reference to the scene region object at a given position or null if there's no such region.


IsBlockedAt(X, Y)

Queries whether the scene is blocked at a given point.

Parameters

X
The X coordinate of the point within scene to be tested
Y
The Y coordinate of the point within scene to be tested

Return value

Returns true if the scene is blocked at given coordinates.


IsWalkableAt(X, Y)

Queries whether the scene is walkable at a given point.

Parameters

X
The X coordinate of the point within scene to be tested
Y
The Y coordinate of the point within scene to be tested

Return value

Returns true if the scene is walkable at given coordinates.


GetScaleAt(X, Y)

Queries a scale factor at a given point of the scene.

Parameters

X
The X coordinate of the point within scene to be queried
Y
The Y coordinate of the point within scene to be queried

Return value

Returns the scale factor at given coordinates (in percent).


GetRotationAt(X, Y)

Queries a sprite rotation factor at a given point of the scene.

Parameters

X
The X coordinate of the point within scene to be queried
Y
The Y coordinate of the point within scene to be queried

Return value

Returns the sprite rotation factor at given coordinates (in degrees).


IsPointInViewport(X, Y)

Queries whether a given point is lying within the current scene viewport.

Parameters

X
The X coordinate of the point to be tested
Y
The Y coordinate of the point to be tested

Return value

Returns true if the specified point lies within the scene viewport.


FadeOut(Duration, TargetRed, TargetGreen, TargetBlue, TargetAlpha)
FadeOutAsync(Duration, TargetRed, TargetGreen, TargetBlue, TargetAlpha)

Fades the scene out to a specified color.

Parameters

Duration
Specifies how long it will take to fade out, in milliseconds (optional, default=500)
TargetRed
The Red component of a target fade color (optional, default=0)
TargetGreen
The Green component of a target fade color (optional, default=0)
TargetBlue
The Blue component of a target fade color (optional, default=0)
TargetAlpha
The Alpha component (opacity) of a target fade color (optional, default=255)

Remarks

The FadeOut method blocks the script execution until the fading is over, while the FadeOutAsync method returns immediately.


FadeIn(Duration, SourceRed, SourceGreen, SourceBlue, SourceAlpha)
FadeInAsync(Duration, SourceRed, SourceGreen, SourceBlue, SourceAlpha)

Fades the scene in from a specified color.

Parameters

Duration
Specifies how long it will take to fade in, in milliseconds (optional, default=500)
SourceRed
The Red component of the initial fade color (optional, default=0)
SourceGreen
The Green component of the initial fade color (optional, default=0)
SourceBlue
The Blue component of the initial fade color (optional, default=0)
SourceAlpha
The Alpha component (opacity) of the initial fade color (optional, default=255)

Remarks

The FadeIn method blocks the script execution until the fading is over, while the FadeInAsync method returns immediately.


GetFadeColor()

Gets the current fading color.

Return value

Returns the current fading color in the encoded color format.

Remarks

You can use the GetRValue(), GetGValue(), GetBValue() and GetAValue() functions to extract individual color components.


CreateEntity(Name)

Creates a new entity object.

Parameters

Name
The name of the entity object (optional)

Return value

Returns a reference to the newly created entity.


DeleteEntity(Entity)

Destroys a entity object.

Parameters

Entity
The entity object to be destroyed

AddLayer(LayerName)

Adds a new layer to the top of the scene

Parameters

LayerName
The name of the new layer

Return value

Returns a reference to the newly created layer object.


InsertLayer(Index, LayerName)

Inserts a new layer to the scene

Parameters

Index
The position within layers where the new layer is to be inserted
LayerName
The name of the new layer

Return value

Returns a reference to the newly created layer object.


DeleteLayer(LayerIndex)
DeleteLayer(LayerObject)

Permanently removes a scene layer

Parameters

LayerIndex
The index of the layer to be deleted
LayerObject
The layer object to be deleted

Return value

Returns true if the layer was successfuly deleted.


EnableNode3D(NodeName)

Enables a 3D walkplane or blocked object

Parameters

NodeName
The name of the node to be enabled.

Return value

Returns true if the node has been successfuly enabled.

Remarks

The scene must have a 3D geometry assigned for this method to work.


DisableNode3D(NodeName)

Disables a 3D walkplane or blocked object

Parameters

NodeName
The name of the node to be disabled.

Return value

Returns true if the node has been successfuly disabled.

Remarks

The scene must have a 3D geometry assigned for this method to work.


IsNode3DEnabled(NodeName)

Checks whether a specified 3D walkplane or blocked object is enabled.

Parameters

NodeName
The name of the node to be queried.

Return value

Returns true if the specified 3D scene node exists and is currently enabled.


EnableLight(LightName)

Enables a 3D light within the scene

Parameters

LightName
The name of the light to be enabled.

Return value

Returns true if the light has been successfuly enabled.

Remarks

The scene must have a 3D geometry assigned for this method to work.


DisableLight(LightName)

Disables a 3D light within the scene

Parameters

LightName
The name of the light to be disabled.

Return value

Returns true if the light has been successfuly disabled.

Remarks

The scene must have a 3D geometry assigned for this method to work.


IsLightEnabled(LightName)

Checks whether a specified 3D light is enabled.

Parameters

LightName
The name of the light to be queried.

Return value

Returns true if the specified light exists and is currently enabled.


SetLightColor(LightName, Color)

Changes the color of a 3D light

Parameters

LightName
The name of the light to be changed
Color
The RGB color to be assigned to the light

Return value

Returns true if the light color has been successfuly changed.

Remarks

The scene must have a 3D geometry assigned for this method to work.


GetLightColor(LightName)

Queries the color of a 3D light

Parameters

LightName
The name of the light to be queried

Return value

Returns the color of the light in RGB format.

Remarks

The scene must have a 3D geometry assigned for this method to work. Use the global functions GetRValue(), GetGValue() and GetBValue() to get individual color components.


GetLightPosition(LightName)

Queries the position of a 3D light

Parameters

LightName
The name of the light to be queried

Return value

Returns an object providing three properties, X, Y and Z, representing the light position in 3D space.

Remarks

The scene must have a 3D geometry assigned for this method to work.


GetLightName(LightIndex)

Queries the name of a specified 3D light

Parameters

LightIndex
The index of the light to be queried

Return value

Returns the name of the light at specified index or null if the index is invalid.

Remarks

You can use a loop from 0 to Scene.NumLights - 1 to query the names of all lights in the scene.


SetActiveCamera(CameraName)

Switches a camera used to display 3D objects in scene

Parameters

CameraName
The name of the camera to be used.

Return value

Returns true if the camera has been successfuly switched.

Remarks

The scene must have a 3D geometry assigned for this method to work.


EnableFog(Color, Start, End)

Enables linear fog within the scene, which affects the 3D actors

Parameters

Color
The fog color
Start
The start of the fog range (in scene geometry units)
End
The end of the fog range (in scene geometry units)

Remarks

Use the MakeRGBA() function to encode the color value.


DisableFog()

Disables fog within the scene.


SetViewport(X, Y, Width, Height)

Sets scene viewport to specified values.

Parameters

X
Viewport X position on screen
Y
Viewport Y position on screen
Width
Viewport width
Height
Viewport width

Remarks

This method only affects the current scene (unlike Game.SetSceneViewport). Call this method without any parameters to set viewport to full screen.