Virtual Stage

From HEWIKI
(Difference between revisions)
Jump to: navigation, search
(moved to category GUIXML)
(formatting changes and added another example)
Line 1: Line 1:
 
{{tocright}}
 
{{tocright}}
 
For more information, please see the sections on:
 
 
* [[Technical:Prop Buckets|Prop Buckets]]
 
* [[Technical:Graphical Functions | GUIFunctions]]
 
* [[Technical:Vector Functions|Vector Functions]]
 
* [[GUIXML]]
 
 
 
== Overview ==
 
== Overview ==
  
Line 15: Line 7:
  
 
As of this writing, the primary uses for Virtual Stages are the crafting system and character manager.  These are places in the game where it is desired to see 3D objects, but without them being in the actual game world. The instances come from assets stored in [[Technical:Prop Buckets|Prop Buckets]], but it is not necessary to use the same bucket for each one.
 
As of this writing, the primary uses for Virtual Stages are the crafting system and character manager.  These are places in the game where it is desired to see 3D objects, but without them being in the actual game world. The instances come from assets stored in [[Technical:Prop Buckets|Prop Buckets]], but it is not necessary to use the same bucket for each one.
 
  
 
You can create and manipulate a virtual stage with various [[Technical:Graphical Function | GUIFunctions]].
 
You can create and manipulate a virtual stage with various [[Technical:Graphical Function | GUIFunctions]].
Line 44: Line 35:
 
* PFM
 
* PFM
  
  Needs documentation
+
<br>
  
 
== Stage Manipulation ==
 
== Stage Manipulation ==
Line 50: Line 41:
 
==== Create Stage ====
 
==== Create Stage ====
  
<hsl>  
+
Creates a new [[Technical:Virtual Stage|Virtual Stage]] for rendering, with a render target texture of the specified width and height.  On some video cards, width and height should both be powers of 2 (64, 128, 256, 512 or 1024). Returns false if the stage already exists or width/height values are invalid.
 +
<hsl>
 
StageCreate(stageName as string, width as int, height as int) as boolean
 
StageCreate(stageName as string, width as int, height as int) as boolean
 
</hsl>
 
</hsl>
  
Creates a new [[Technical:Virtual Stage|Virtual Stage]] for rendering, with a render target texture of the specified width and height.  On some video cards, width and height should both be powers of 2 (64, 128, 256, 512 or 1024). Returns false if the stage already exists or width/height values are invalid.
+
<br>
 
+
  
 
=== Destroy Stage ===
 
=== Destroy Stage ===
 +
 +
Destroys a stage.  If a stage is not destroyed with this command, it will hang around until the client is shut down.  There is no penalty for attempting to destroy a stage that was already deleted.
 
<hsl>
 
<hsl>
  StageDestroy(stageName as string)
+
StageDestroy(stageName as string)
 
</hsl>
 
</hsl>
  
Destroys a stage.  If a stage is not destroyed with this command, it will hang around until the client is shut down.  There is no penalty for attempting to destroy a stage that was already deleted.
+
<br>
 
+
  
 
==== Resize Stage ====
 
==== Resize Stage ====
  
 +
Resizes the render target texture of an existing [[Technical:Virtual Stage|Virtual Stage]]. Returns false if the stage does not exist, or width/height values are invalid.
 
<hsl>
 
<hsl>
  StageResize(stageName as string, width as int, height as int) as boolean
+
StageResize(stageName as string, width as int, height as int) as boolean
 
</hsl>
 
</hsl>
  
Resizes the render target texture of an existing [[Technical:Virtual Stage|Virtual Stage]]. Returns false if the stage does not exist, or width/height values are invalid.
+
<br>
  
 
==== Change Stage Backdrop Color ====
 
==== Change Stage Backdrop Color ====
  
 +
Changes the backdrop color for a [[Technical:Virtual Stage|Virtual Stage]].  Color is specified by string in the format #R,G,B,A where each value is a float from 0 to 1. Alpha determines the stage's full-scene bloom (0=no bloom, 1=max). Returns false if the stage does not exist.
 
<hsl>
 
<hsl>
 
StageSetBackdropColor(stageName as string, color as string) as boolean
 
StageSetBackdropColor(stageName as string, color as string) as boolean
 
</hsl>
 
</hsl>
  
Changes the backdrop color for a [[Technical:Virtual Stage|Virtual Stage]].  Color is specified by string in the format #R,G,B,A where each value is a float from 0 to 1. Alpha determines the stage's full-scene bloom (0=no bloom, 1=max). Returns false if the stage does not exist.
+
<br>
  
 
==== Copy Character Into Virtual Stage ====
 
==== Copy Character Into Virtual Stage ====
 +
 +
This function copies an entire character, including their inventory, to a virtual stage. One possible use of this function might be to display a character's invetory. As of this writing, it does not copy objects that are "held" by the character. To move those items as well, a separate prop bucket is needed.
 
<hsl>
 
<hsl>
 
CopyCharacterIntoVirtualStage(original as NodeRef of Class HBNode, stagename as String) as NodeRef of Class HBNode
 
CopyCharacterIntoVirtualStage(original as NodeRef of Class HBNode, stagename as String) as NodeRef of Class HBNode
 
</hsl>
 
</hsl>
  
This function copies an entire character, including their inventory, to a virtual stage. One possible use of this function might be to display a character's invetory. As of this writing, it does not copy objects that are "held" by the character. To move those items as well, a separate prop bucket is needed.
+
<br>
  
 
== Stage Camera ==
 
== Stage Camera ==
  
 
=== Get Stage Camera Zoom ===
 
=== Get Stage Camera Zoom ===
 +
 +
Returns a floating point number which indicates how close the stage's camera is zooming in.
 
<hsl>
 
<hsl>
  StageGetZoom(stageName as string) as float
+
StageGetZoom(stageName as string) as float
 
</hsl>
 
</hsl>
  
Returns a floating point number which indicates how close the stage's camera is zooming in.
+
<br>
  
 
==== Set Stage Camera Zoom ====
 
==== Set Stage Camera Zoom ====
  
 +
Sets the zoom factor for the [[Technical:Virtual Stage|Virtual Stage]]'s camera. Returns false if the stage does not exist.  The larger the number, the smaller the object on the stage appears.  Default value is 1.0, which means display the object at its normal world size, as if you were 1 meter away.  So a zoom of 10.0 would mean display the object as though you were 10 meters away.  There are no minimum or maximum values, though a negative value would mean being on the other side of the object, and a value of 0 would mean being inside of it!
 
<hsl>
 
<hsl>
 
StageSetZoom(stageName as string, zoom as float) as boolean
 
StageSetZoom(stageName as string, zoom as float) as boolean
 
</hsl>
 
</hsl>
  
Sets the zoom factor for the [[Technical:Virtual Stage|Virtual Stage]]'s camera. Returns false if the stage does not exist.  The larger the number, the smaller the object on the stage appears.  Default value is 1.0, which means display the object at its normal world size, as if you were 1 meter away.  So a zoom of 10.0 would mean display the object as though you were 10 meters away.  There are no minimum or maximum values, though a negative value would mean being on the other side of the object, and a value of 0 would mean being inside of it!
+
<br>
  
 
==== Set AutoZoom ====
 
==== Set AutoZoom ====
  
 +
Tells the [[Technical:Virtual Stage|Virtual Stage]] to automatically set its zoom factor to fit everything in its scene. Returns false if the stage does not exist.
 
<hsl>
 
<hsl>
 
StageAutoZoom(stageName as string) as boolean
 
StageAutoZoom(stageName as string) as boolean
 
</hsl>
 
</hsl>
  
Tells the [[Technical:Virtual Stage|Virtual Stage]] to automatically set its zoom factor to fit everything in its scene. Returns false if the stage does not exist.
+
<br>
  
 
=== Get Camera Rotation ===
 
=== Get Camera Rotation ===
  
 +
Returns a vector with the direction that the camera is currently pointing from, in (pitch, yaw, roll) degrees.
 
<hsl>
 
<hsl>
  StageGetRotation(stageName) as vector3
+
StageGetRotation(stageName) as vector3
 
</hsl>
 
</hsl>
  
Returns a vector with the direction that the camera is currently pointing from, in (pitch, yaw, roll) degrees.
+
<br>
  
 
==== Set Camera Rotation ====
 
==== Set Camera Rotation ====
  
 +
Sets the camera rotation for the specified [[Technical:Virtual Stage|Virtual Stage]], in (pitch,yaw,roll) format, in degrees.  The camera automatically positions itself so that it faces (0,0,0) whatever its rotation may be. Returns false if the stage does not exist.
 
<hsl>
 
<hsl>
 
StageSetRotation(stageName as string, rotation as vector3) as boolean
 
StageSetRotation(stageName as string, rotation as vector3) as boolean
 
</hsl>
 
</hsl>
 
Sets the camera rotation for the specified [[Technical:Virtual Stage|Virtual Stage]], in (pitch,yaw,roll) format, in degrees.  The camera automatically positions itself so that it faces (0,0,0) whatever its rotation may be. Returns false if the stage does not exist.
 
  
 
Note:  In this context, rotation does not mean speed of rotation (that would be delta).  It means the relative angle that the camera is pointing from.  For example:  If the stage is looking at a model of a coffeecup, and rotation is set to (0,90,0), then the view of the coffeecup will change so it is being looked at from the righthand side.
 
Note:  In this context, rotation does not mean speed of rotation (that would be delta).  It means the relative angle that the camera is pointing from.  For example:  If the stage is looking at a model of a coffeecup, and rotation is set to (0,90,0), then the view of the coffeecup will change so it is being looked at from the righthand side.
 +
 +
<br>
  
 
==== Set Camera Rotation Delta ====
 
==== Set Camera Rotation Delta ====
  
 +
Sets the amount by which that the [[Technical:Virtual Stage|Virtual Stage]]'s camera will rotate each second, in degrees. Returns false if the stage does not exist.  So if the delta is 90, then the image rotates 90 degrees every second, and would turn completely around every 4 seconds.  For reference, at your typical car show where a car is on a big pedestal that is rotating, the delta might be 10.  10 degrees per second, or a full rotation in 36 seconds.
 
<hsl>
 
<hsl>
 
StageSetDeltaRotation(stageName as string, deltaRotation as vector3) as boolean
 
StageSetDeltaRotation(stageName as string, deltaRotation as vector3) as boolean
 
</hsl>
 
</hsl>
  
Sets the amount by which that the [[Technical:Virtual Stage|Virtual Stage]]'s camera will rotate each second, in degrees. Returns false if the stage does not exist.  So if the delta is 90, then the image rotates 90 degrees every second, and would turn completely around every 4 seconds.  For reference, at your typical car show where a car is on a big pedestal that is rotating, the delta might be 10.  10 degrees per second, or a full rotation in 36 seconds.
+
<br>
  
 
====Set Auto Center on Objects====
 
====Set Auto Center on Objects====
 +
 +
Client function.  If set to true, the virtual stage camera will focus on the center of the stage's collective bounding box; otherwise the camera will focus on (0,0,0).
 
<hsl>
 
<hsl>
 
StageSetAutoCenterOnObjects(stageName as string, autoCenter as boolean)
 
StageSetAutoCenterOnObjects(stageName as string, autoCenter as boolean)
 
</hsl>
 
</hsl>
  
Client function.  If set to true, the virtual stage camera will focus on the center of the stage's collective bounding box; otherwise the camera will focus on (0,0,0).
+
<br>
  
 
=== Camera Forward Vector ===
 
=== Camera Forward Vector ===
  
 +
This function takes a stage name, and returns a vector3 value which points in the direction that the camera is currently looking.
 
<hsl>
 
<hsl>
  StageGetCameraForwardVector(stageName as string) as vector3
+
StageGetCameraForwardVector(stageName as string) as vector3
 
</hsl>
 
</hsl>
  
This function takes a stage name, and returns a vector3 value which points in the direction that the camera is currently looking.
+
<br>
  
 
=== Camera Right Vector ===
 
=== Camera Right Vector ===
  
 +
This function takes a stage name, and returns a vector3 value which points 90 degrees to the right of where the camera is looking.  For example, if you face forward and then lift your right arm to point to the right, where you are looking is the forward vector, and where your right arm is pointing is the right vector.  As the camera angle changes, the right vector moves with it.
 
<hsl>
 
<hsl>
  StageGetCameraRightVector(stageName as string) as vector3
+
StageGetCameraRightVector(stageName as string) as vector3
 
</hsl>
 
</hsl>
  
This function takes a stage name, and returns a vector3 value which points 90 degrees to the right of where the camera is looking.  For example, if you face forward and then lift your right arm to point to the right, where you are looking is the forward vector, and where your right arm is pointing is the right vector.  As the camera angle changes, the right vector moves with it.
+
<br>
  
 
=== Camera Up Vector ===
 
=== Camera Up Vector ===
  
 +
This function takes a stage name, and returns a vector3 value which points up at 90 degrees from (points in the direction??) the direction that the camera is currently looking.  For example, if you face forward and look straight ahead, where you are looking is the Forward Vector, and a line from your toes to the crown of your head is the up vector.  This vector stays at 90 degrees, so as the camera angle changes, the up vector changes accordingly.
 
<hsl>
 
<hsl>
  StageGetCameraUpVector(stageName as string) as vector3
+
StageGetCameraUpVector(stageName as string) as vector3
 
</hsl>
 
</hsl>
  
This function takes a stage name, and returns a vector3 value which points up at 90 degrees from the direction that the camera is currently looking.  For example, if you face forward and look straight ahead, where you are looking is the Forward Vector, and a line from your toes to the crown of your head is the up vector.  This vector stays at 90 degrees, so as the camera angle changes, the up vector changes accordingly.
+
<br>
 
+
 
+
This function takes a stage name, and returns a vector3 value which points in the direction that the camera is currently looking.
+
  
 
== Stage Lighting ==
 
== Stage Lighting ==
Line 177: Line 182:
 
=== Get Directional Light ===
 
=== Get Directional Light ===
  
 +
Gets the properties of the [[Technical:Virtual Stage|Virtual Stage]]'s directional light.  The colors' alpha is ignored. Returns false if the stage does not exist.  A Directional Light is a simulated "sun" that tells the game world which direction that light is coming from (or to be specific, which way that light is going).  For example, a direction vector of (0,-1,0) would mean that light was coming down from directly overhead.  A direction vector of
 
<hsl>
 
<hsl>
StageGetDirectionalLight(stageName as string, ambientColor as string, \
+
StageGetDirectionalLight(stageName as string, ambientColor as string, diffuseColor as string, lightDirection as vector3) as boolean
          diffuseColor as string, lightDirection as vector3) as boolean
+
 
</hsl>
 
</hsl>
  
 
+
<br>
Gets the properties of the [[Technical:Virtual Stage|Virtual Stage]]'s directional light.  The colors' alpha is ignored. Returns false if the stage does not exist.  A Directional Light is a simulated "sun" that tells the game world which direction that light is coming from (or to be specific, which way that light is going).  For example, a direction vector of (0,-1,0) would mean that light was coming down from directly overhead.  A direction vector of
+
  
 
=== Set Directional Light ===
 
=== Set Directional Light ===
  
 +
Sets the properties of the [[Technical:Virtual Stage|Virtual Stage]]'s directional light.  The colors' alpha is ignored. Returns false if the stage does not exist.
 
<hsl>
 
<hsl>
StageSetDirectionalLight(stageName as string, ambientColor as string, \
+
StageSetDirectionalLight(stageName as string, ambientColor as string, diffuseColor as string, lightDirection as vector3) as boolean
          diffuseColor as string, lightDirection as vector3) as boolean
+
 
</hsl>
 
</hsl>
  
 
+
<br>
Sets the properties of the [[Technical:Virtual Stage|Virtual Stage]]'s directional light.  The colors' alpha is ignored. Returns false if the stage does not exist.
+
 
+
  
 
=== Set Fog Color ===
 
=== Set Fog Color ===
  
 +
Sets the distance-based fog color for the [[Technical:Virtual Stage|Virtual Stage]], in #R,G,B,A format where each value is a float from 0 to 1.  Alpha determines the thickness of the fog. Returns false if the stage does not exist.
 
<hsl>
 
<hsl>
 
StageSetFog(stageName as string, fogColor as string) as boolean
 
StageSetFog(stageName as string, fogColor as string) as boolean
 
</hsl>
 
</hsl>
  
Sets the distance-based fog color for the [[Technical:Virtual Stage|Virtual Stage]], in #R,G,B,A format where each value is a float from 0 to 1.  Alpha determines the thickness of the fog. Returns false if the stage does not exist.
+
<br>
 
+
  
 
== Stage Instances ==
 
== Stage Instances ==
Line 209: Line 211:
 
=== Activate instance ===
 
=== Activate instance ===
  
  (which of these is more accurate?)
+
Activates the specified node, making it renderable. If the stage name is "", the node is rendered in the Area.  Otherwise, it is rendered by the specified Virtual Stage. If the node or stage could not be found, this function returns a value of FALSE. If the instance is successfully activated, this function returns a value of TRUE.
 
<hsl>
 
<hsl>
 
ActivateInstance(instance as noderef, stageName as string) as boolean
 
ActivateInstance(instance as noderef, stageName as string) as boolean
 
ActivateInstance(instanceID as ID, stageName as string) as boolean
 
ActivateInstance(instanceID as ID, stageName as string) as boolean
 
</hsl>
 
</hsl>
 +
 +
<br>
  
Activates the specified node, making it renderable.  If the stage name is "", the node is rendered in the Area.  Otherwise, it is rendered by the specified Virtual Stage.
+
=== Inactivate instance ===
 
+
If the node or stage could not be found, this function returns a value of FALSE. 
+
If the instance is successfully activated, this function returns a value of TRUE.
+
 
+
==== Inactivate instance ====
+
 
+
  
 +
Inactivates the specified node, making it unrenderable. Returns FALSE if the node could not be found.
 
<hsl>
 
<hsl>
 
InactivateInstance(instance as noderef) as boolean
 
InactivateInstance(instance as noderef) as boolean
 
</hsl>
 
</hsl>
  
Inactivates the specified node, making it unrenderable. Returns FALSE if the node could not be found.
+
<br>
 
+
 
+
There are conflicting reports on whether to use an ID or a noderef in ActivateInstance and InactivateInstance.  At most recent report, ActivateInstance uses an ID, and InactivateInstance uses a noderef.  Stay tuned.  :)
+
  
 
=== Get Instances on Stage ===
 
=== Get Instances on Stage ===
  
 +
Will generate a list of all of the instances which are currently on a stage. Will generate an error if not called on a valid stage name.
 
<hsl>
 
<hsl>
  StageGetInstances(stageName as string, instanceList references list of noderef) as boolean
+
StageGetInstances(stageName as string, instanceList references list of noderef) as boolean
 
</hsl>
 
</hsl>
  
Will generate a list of all of the instances which are currently on a stage.
+
<br>
  
Will generate an error if not called on a valid stage name.
+
== Examples ==
 
+
== Example ==
+
  
 
Suppose you wish to place a directional light which shines onto the stage from a 45-degree angle off the horizon.  To set the directional light, first this angle must be converted into vector3 format.  This is done with the <code>Spherical2XYZ()</code> exposed function:
 
Suppose you wish to place a directional light which shines onto the stage from a 45-degree angle off the horizon.  To set the directional light, first this angle must be converted into vector3 format.  This is done with the <code>Spherical2XYZ()</code> exposed function:
Line 255: Line 250:
  
  
 +
The following code will create a Virtual Stage and copy the character into it. The camera is adjusted so it's looking at the front of the character, centered on the character and zoomed out so the entire character it visible. Then a GUIPanel is created to show the virtual stage.
 +
<hsl>
 +
//setup the virtual stage
 +
stageName as String = "ExampleStage"
 +
StageCreate(stageName, 256, 256)
 +
CopyCharacterIntoVirtualStage(GetAccountID(), stageName)
 +
StageSetRotation(stageName, (0,180,0))
 +
StageAutoZoom(stageName)
 +
StageSetAutoCenterOnObjects(stageName, true)
 +
 
 +
//create a GUI panel to show the virtual stage
 +
panel as NodeRef of Class GUIControl = CreateNodeFromPrototype("_panel")
 +
panel.build = true
 +
panel.name = stageName
 +
panel.size.x = 256
 +
panel.size.y = 256
 +
panel.texture = ":" + stageName
 +
</hsl>
  
Need expanded example
+
<br>
 +
 
 +
== See Also ==
 +
 
 +
* [[Technical:Prop Buckets|Prop Buckets]]
 +
* [[Technical:Graphical Functions | GUIFunctions]]
 +
* [[Technical:Vector Functions|Vector Functions]]
 +
* [[GUIXML]]
 +
* [[GUI]]
  
 
[[Category:GUIXML|Virtual stage]]
 
[[Category:GUIXML|Virtual stage]]
[[Category:Virtual stages| ]]
+
[[Category:Virtual stage]]
 
[[Category:Functions|Virtual stage]]
 
[[Category:Functions|Virtual stage]]

Revision as of 20:16, 11 November 2011

Contents

Overview

A virtual stage is a separate 3D world that can be created for displaying assets independent of the world. The stage renders to a texture which can then be used by the GUI. These are useful for a separate window on things like inventory items, etc. These created textures may also be used for objects in the world.

Virtual Stages are not persistent -- they are created and destroyed as needed.

As of this writing, the primary uses for Virtual Stages are the crafting system and character manager. These are places in the game where it is desired to see 3D objects, but without them being in the actual game world. The instances come from assets stored in Prop Buckets, but it is not necessary to use the same bucket for each one.

You can create and manipulate a virtual stage with various GUIFunctions.

Related Functions

There are certain basic categories of functions to deal with a Virtual Stage:

StageSaveTexture(stageNameParam as String, FQNparam as String, formatParam as String) as Boolean

StageSaveTexture accepts at a minimum the following image formats:


Stage Manipulation

Create Stage

Creates a new Virtual Stage for rendering, with a render target texture of the specified width and height. On some video cards, width and height should both be powers of 2 (64, 128, 256, 512 or 1024). Returns false if the stage already exists or width/height values are invalid.

StageCreate(stageName as string, width as int, height as int) as boolean


Destroy Stage

Destroys a stage. If a stage is not destroyed with this command, it will hang around until the client is shut down. There is no penalty for attempting to destroy a stage that was already deleted.

StageDestroy(stageName as string)


Resize Stage

Resizes the render target texture of an existing Virtual Stage. Returns false if the stage does not exist, or width/height values are invalid.

StageResize(stageName as string, width as int, height as int) as boolean


Change Stage Backdrop Color

Changes the backdrop color for a Virtual Stage. Color is specified by string in the format #R,G,B,A where each value is a float from 0 to 1. Alpha determines the stage's full-scene bloom (0=no bloom, 1=max). Returns false if the stage does not exist.

StageSetBackdropColor(stageName as string, color as string) as boolean


Copy Character Into Virtual Stage

This function copies an entire character, including their inventory, to a virtual stage. One possible use of this function might be to display a character's invetory. As of this writing, it does not copy objects that are "held" by the character. To move those items as well, a separate prop bucket is needed.

CopyCharacterIntoVirtualStage(original as NodeRef of Class HBNode, stagename as String) as NodeRef of Class HBNode


Stage Camera

Get Stage Camera Zoom

Returns a floating point number which indicates how close the stage's camera is zooming in.

StageGetZoom(stageName as string) as float


Set Stage Camera Zoom

Sets the zoom factor for the Virtual Stage's camera. Returns false if the stage does not exist. The larger the number, the smaller the object on the stage appears. Default value is 1.0, which means display the object at its normal world size, as if you were 1 meter away. So a zoom of 10.0 would mean display the object as though you were 10 meters away. There are no minimum or maximum values, though a negative value would mean being on the other side of the object, and a value of 0 would mean being inside of it!

StageSetZoom(stageName as string, zoom as float) as boolean


Set AutoZoom

Tells the Virtual Stage to automatically set its zoom factor to fit everything in its scene. Returns false if the stage does not exist.

StageAutoZoom(stageName as string) as boolean


Get Camera Rotation

Returns a vector with the direction that the camera is currently pointing from, in (pitch, yaw, roll) degrees.

StageGetRotation(stageName) as vector3


Set Camera Rotation

Sets the camera rotation for the specified Virtual Stage, in (pitch,yaw,roll) format, in degrees. The camera automatically positions itself so that it faces (0,0,0) whatever its rotation may be. Returns false if the stage does not exist.

StageSetRotation(stageName as string, rotation as vector3) as boolean

Note: In this context, rotation does not mean speed of rotation (that would be delta). It means the relative angle that the camera is pointing from. For example: If the stage is looking at a model of a coffeecup, and rotation is set to (0,90,0), then the view of the coffeecup will change so it is being looked at from the righthand side.


Set Camera Rotation Delta

Sets the amount by which that the Virtual Stage's camera will rotate each second, in degrees. Returns false if the stage does not exist. So if the delta is 90, then the image rotates 90 degrees every second, and would turn completely around every 4 seconds. For reference, at your typical car show where a car is on a big pedestal that is rotating, the delta might be 10. 10 degrees per second, or a full rotation in 36 seconds.

StageSetDeltaRotation(stageName as string, deltaRotation as vector3) as boolean


Set Auto Center on Objects

Client function. If set to true, the virtual stage camera will focus on the center of the stage's collective bounding box; otherwise the camera will focus on (0,0,0).

StageSetAutoCenterOnObjects(stageName as string, autoCenter as boolean)


Camera Forward Vector

This function takes a stage name, and returns a vector3 value which points in the direction that the camera is currently looking.

StageGetCameraForwardVector(stageName as string) as vector3


Camera Right Vector

This function takes a stage name, and returns a vector3 value which points 90 degrees to the right of where the camera is looking. For example, if you face forward and then lift your right arm to point to the right, where you are looking is the forward vector, and where your right arm is pointing is the right vector. As the camera angle changes, the right vector moves with it.

StageGetCameraRightVector(stageName as string) as vector3


Camera Up Vector

This function takes a stage name, and returns a vector3 value which points up at 90 degrees from (points in the direction??) the direction that the camera is currently looking. For example, if you face forward and look straight ahead, where you are looking is the Forward Vector, and a line from your toes to the crown of your head is the up vector. This vector stays at 90 degrees, so as the camera angle changes, the up vector changes accordingly.

StageGetCameraUpVector(stageName as string) as vector3


Stage Lighting

Get Directional Light

Gets the properties of the Virtual Stage's directional light. The colors' alpha is ignored. Returns false if the stage does not exist. A Directional Light is a simulated "sun" that tells the game world which direction that light is coming from (or to be specific, which way that light is going). For example, a direction vector of (0,-1,0) would mean that light was coming down from directly overhead. A direction vector of

StageGetDirectionalLight(stageName as string, ambientColor as string, diffuseColor as string, lightDirection as vector3) as boolean


Set Directional Light

Sets the properties of the Virtual Stage's directional light. The colors' alpha is ignored. Returns false if the stage does not exist.

StageSetDirectionalLight(stageName as string, ambientColor as string, diffuseColor as string, lightDirection as vector3) as boolean


Set Fog Color

Sets the distance-based fog color for the Virtual Stage, in #R,G,B,A format where each value is a float from 0 to 1. Alpha determines the thickness of the fog. Returns false if the stage does not exist.

StageSetFog(stageName as string, fogColor as string) as boolean


Stage Instances

Activate instance

Activates the specified node, making it renderable. If the stage name is "", the node is rendered in the Area. Otherwise, it is rendered by the specified Virtual Stage. If the node or stage could not be found, this function returns a value of FALSE. If the instance is successfully activated, this function returns a value of TRUE.

ActivateInstance(instance as noderef, stageName as string) as boolean
ActivateInstance(instanceID as ID, stageName as string) as boolean


Inactivate instance

Inactivates the specified node, making it unrenderable. Returns FALSE if the node could not be found.

InactivateInstance(instance as noderef) as boolean


Get Instances on Stage

Will generate a list of all of the instances which are currently on a stage. Will generate an error if not called on a valid stage name.

StageGetInstances(stageName as string, instanceList references list of noderef) as boolean


Examples

Suppose you wish to place a directional light which shines onto the stage from a 45-degree angle off the horizon. To set the directional light, first this angle must be converted into vector3 format. This is done with the Spherical2XYZ() exposed function:

LightDirection as vector3
ambient as string = "#.2, .2, .2, 1"   // This is the "grey" color
diffuse as string = "#1,1,1,1"         // This is a "white" color
 
Spherical2XYZ(0.0, 45.0, 1.0, LightDirection)
StageSetDirectionalLight("Stage", ambient, diffuse, LightDirection)  // Gives a little bit of ambient light, and a lot of diffuse


The following code will create a Virtual Stage and copy the character into it. The camera is adjusted so it's looking at the front of the character, centered on the character and zoomed out so the entire character it visible. Then a GUIPanel is created to show the virtual stage.

//setup the virtual stage
stageName as String = "ExampleStage"
StageCreate(stageName, 256, 256)
CopyCharacterIntoVirtualStage(GetAccountID(), stageName)
StageSetRotation(stageName, (0,180,0))
StageAutoZoom(stageName)
StageSetAutoCenterOnObjects(stageName, true)
 
//create a GUI panel to show the virtual stage
panel as NodeRef of Class GUIControl = CreateNodeFromPrototype("_panel")
panel.build = true
panel.name = stageName
panel.size.x = 256
panel.size.y = 256
panel.texture = ":" + stageName


See Also

Personal tools
Namespaces
Variants
Actions
Navigation
Toolbox