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.
There are certain basic categories of functions to deal with a Virtual Stage:
- Creating, destroying, and resizing the stage
- Dealing with Stage Instances
- Getting and setting camera vectors
- Getting and setting light vectors
StageSaveTexture(stageNameParam as String, FQNparam as String, formatParam as String) as Boolean
StageSaveTexture accepts at a minimum the following image formats:
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
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)
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
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
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
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
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
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
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