ShiVa Book Update for v18

SPINAL BOOKS Books with Real Backbone

Introduction to 3D

Programming with ShiVa® ***Update for v1.8***

by

Simon Harwood

UPDATE FOR SHIVA 1.8

ShiVa Book Update for v1.8 Page 1

Table of Contents

INTRODUCTION TO SHIVA v1.8 ............................................................................................................... 3

CHAPTER 6 – Particular Trails .................................................................................................................. 7

CHAPTER 7 – Sounds Good ..................................................................................................................... 8

CHAPTER 8 – It’s a Material World ......................................................................................................... 9

CHAPTER 9 – Heads Up ......................................................................................................................... 10

Check (Component) ...................................................................................................................... 10

CopyCheckStateToRegister (Action) ............................................................................................. 11

CopyEditTextToRegister (Action) .................................................................................................. 12

CopyListItemTextToRegister (Action) ........................................................................................... 12

CopyListLastSelectedItemToRegister (Action) .............................................................................. 13

CopyTagToRegister (Action) .......................................................................................................... 13

InterpolateHeight (Action) ............................................................................................................ 13

InterpolateWidth (Action) ............................................................................................................. 14

MatchScreenSpaceBottomLeftCorner (Action) ............................................................................ 14

MatchScreenSpaceBottomRightCorner (Action) .......................................................................... 15

MatchScreenSpaceCenter (Action) ............................................................................................... 15

MatchScreenSpaceHeight (Action) ............................................................................................... 15

MatchScreenSpaceTopLeftCorner (Action) .................................................................................. 16

MatchScreenSpaceTopRightCorner (Action) ................................................................................ 16

MatchScreenSpaceWidth (Action) ................................................................................................ 17

SetCheckState (Action) ................................................................................................................. 17

SetCheckText (Action) ................................................................................................................... 18

SetHeight (Action) ......................................................................................................................... 18

SetWidth (Action) .......................................................................................................................... 19

CHAPTER 10 – Attributed To You .......................................................................................................... 23

CHAPTER 11 – Pure Ambience .............................................................................................................. 29

CHAPTER 16 – Creating a Terrain .......................................................................................................... 38

CHAPTER 18 – THE GAME EDITOR & THE SCENE VIEWER .................................................................... 42

GAME EDITOR ................................................................................................................................... 42

SCENE VIEWER .................................................................................................................................. 43

CHAPTER 19 – THE DATA EXPLORER ..................................................................................................... 45

CHAPTER 20 – THE AIMODEL EDITOR ................................................................................................... 50



CHAPTER 21 – THE SCRIPT EDITOR ....................................................................................................... 53

CHAPTER 22 – OTHER CHANGES ........................................................................................................... 54

APPENDIX 1 – NEW API FUNCTIONS & CONSTANTS ............................................................................. 56

ANIMATION ....................................................................................................................................... 56

APPLICATION ..................................................................................................................................... 56

CACHE ............................................................................................................................................... 60

CAMERA ............................................................................................................................................ 60

DEBUG ............................................................................................................................................... 67

HUD ................................................................................................................................................... 67

INPUT ................................................................................................................................................ 74

MATH ................................................................................................................................................ 75

MICROPHONE ................................................................................................................................... 75

NAVIGATION ..................................................................................................................................... 76

NETWORK .......................................................................................................................................... 77

OBJECT .............................................................................................................................................. 78

PIXELMAP .......................................................................................................................................... 79

PROJECTOR ....................................................................................................................................... 85

SCENE ................................................................................................................................................ 87

SENSOR ............................................................................................................................................. 98

SERVER .............................................................................................................................................. 99

SFX ................................................................................................................................................... 100

SHAPE .............................................................................................................................................. 100

SOUND ............................................................................................................................................ 102

STRING ............................................................................................................................................ 102

SYSTEM............................................................................................................................................ 103

USER ................................................................................................................................................ 107

XML ................................................................................................................................................. 108



INTRODUCTION TO SHIVA v1.8 G’day and welcome to the first of what I hope will be many updates to my ShiVa book. I have decided that, rather than rewriting the whole book each time StoneTrip releases a new version of ShiVa, I would just write an update. These updates will follow, as closely as possible, the original Chapters of the book, and where new options etc. do not fit into a particular Chapter in the book, I’ll put them into their own Chapter of the update. I’ll also list any new API Functions and Constants in a separate Appendix at the end. I’ll be using the official StoneTrip release notes as a guide to the changes from the previous version, so I may miss some things, but hopefully they’ll only be minor and won’t impact on your journey through the ShiVaverse! Well, I think that’s enough waffle from me, so let’s delve into the new world of ShiVa 1.8...... The first thing you may notice, when opening ShiVa 1.8, is the new options available on the right-hand side of the Title Bar, as shown below:

These new options allow you to switch between some predefined Screen layouts, which have been created with a specific functionality in mind. Each of these layouts contains multiple viewports, and a pre-set list of options for each viewport. The layouts are as follows:

Default – A basic layout

Design – A layout for Game Design

Code – A layout for Coding

Preview – A layout for Previewing

Animation – A layout for Animation The names used for these layouts are pretty much self-explanatory, so I’ll just show you some screenshots:



DEFAULT

DESIGN



CODE

PREVIEW



ANIMATION



CHAPTER 6 – Particular Trails The Particle Editor now has a couple of new options:

Use asynchronous update: This option allows the setting of whether to synchronise the Particles with other Particle Emitters. That is, they will start at different times (if not checked), or at the same time (if checked). Priority: This option allows the setting of the priority of the Particle system [0 to 255]. What this means is that you can now set a Particle System to have precedence over other Particle Systems.



CHAPTER 7 – Sounds Good There is only one change to the SoundBank Editor, and that is that it now displays the length of the Sound, as shown below:



CHAPTER 8 – It’s a Material World The only major change to the Material Editor is the addition of a new option for “Shell Alpha Render”, as shown below:

As you can see, the option is to either turn on “Use Z Shell for transparency”, or to turn it off. This option basically uses the Z Shell for transparency calculations.



CHAPTER 9 – Heads Up The HUD has had a bit of a make-over, and there are several new features which I’ll go through one by one. Firstly, a new Component type of “Check” has been added. This is a standard GUI check box, where you can either select, or deselect the Component. This is extremely useful when setting up a HUD to allow the user to select (or deselect) specific options, where there are only two possible outcomes. The options available for this new Component are detailed below:

The first three roll-ups (“General”, “Appearance” & “Events”) are identical to other HUD Components, so I’ll only run through the “Check” roll-up:

Check (Component)

Text: This input box is where the Text to be displayed in the Component is entered. Text Height: This option sets the size of the Font, as a percentage of the height of the Component [0 to 100]. Letter Spacing: This option sets the spacing between the letters of the Text [-100 to 100]. Text Alignment: These options set the alignment of the Text in the Component. The first drop-down lists the options for the horizontal alignment (Centre, Left, Right & Justify), and the second lists the options for the vertical alignment (Centre & Top).



Text Case: This option sets the spacing between the letters, either fixed or variable. Text Font: This option sets the Font Texture to be used. The drop-down lists all available Fonts currently loaded into the application. AntiAliased Text: This option sets whether the Text is antialised, or not, using mipmaps. UnChecked Action: This option allows the setting of an Action that will be called when the Component is “unchecked” (i.e. the Component is currently “checked”, and the Mouse button is pressed with the Mouse Cursor over the Component). NOTE: the drop-down lists all available Actions. Checked Action: This option allows the setting of an Action that will be called when the Component is “checked” (i.e. the Component is currently “unchecked”, and the Mouse button is pressed with the Mouse Cursor over the Component). NOTE: the drop-down lists all available Actions. UnChecked icon: This option allows the setting of an Icon to be used to indicate that the Component is “unchecked”. NOTE: the drop-down lists all available Icons currently loaded into the Application. Checked icon: This option allows the setting of an Icon to be used to indicate that the Component is “checked”. NOTE: the drop-down lists all available Icons currently loaded into the Application.

Secondly, there are several new HUD Action Commands, as follows:

CopyCheckStateToRegister (Action)

This Action allows the State of the selected Check Component to be stored in one of the new HUD Registers, of which there are 4, numbered from 0 to 3.

Component: This option allows the selection of the Check Component whose value is to be stored in a Register. Register: This option allows the selection of the Number of the Register to be used [0 to 3].



As with this Chapter of the Book, I won’t be repeating descriptions of options where they are repeated.

CopyEditTextToRegister (Action)

This Action allows the Text of the selected Edit Component to be stored in one of the HUD Registers.

CopyListItemTextToRegister (Action)

This Action allows the Text of the selected Item of the selected List Component to be stored in one of the HUD Registers.

Item: This option allows the selection of the Item of the List Component whose value is to be stored in a Register [0 to 1000000]. Column: This option allows the selection of the Column of the Item [0 to 1000000].



CopyListLastSelectedItemToRegister (Action)

This Action allows the last selected Item of the selected List Component to be stored in one of the HUD Registers.

CopyTagToRegister (Action)

This Action allows the Tag of the selected Component to be stored in one of the HUD Registers.

InterpolateHeight (Action)

This Action allows the Height of the selected Component to be interpolated over a selected Duration.



Height: This option allows the selection of the percentage of the Height of the Component that is to be the maximum value at the end of the interpolation [0 to 1000].

InterpolateWidth (Action)

This Action allows the Width of the selected Component to be interpolated over a selected Duration.

Width: This option allows the selection of the percentage of the Width of the Component that is to be the maximum value at the end of the interpolation [0 to 1000].

MatchScreenSpaceBottomLeftCorner (Action)

This Action allows the position of the selected Component to be aligned with the bottom left corner of the second selected Component.

Match from: This option allows the selection of the Component that the selected Component will be aligned with.



MatchScreenSpaceBottomRightCorner (Action)

This Action allows the position of the selected Component to be aligned with the bottom right corner of the second selected Component.

MatchScreenSpaceCenter (Action)

This Action allows the position of the selected Component to be aligned with the centre of the second selected Component.

MatchScreenSpaceHeight (Action)



This Action allows the position of the selected Component to be aligned with height of the second selected Component.

MatchScreenSpaceTopLeftCorner (Action)

This Action allows the position of the selected Component to be aligned with the top left corner of the second selected Component.

MatchScreenSpaceTopRightCorner (Action)

This Action allows the position of the selected Component to be aligned with the top right corner of the second selected Component.



MatchScreenSpaceWidth (Action)

This Action allows the position of the selected Component to be aligned with the width of the second selected Component.

SetCheckState (Action)

This Action allows the setting of the State of the selected Check Component.

Checked: This option allows the setting of the selected Component. This is a Boolean value, with True indicating that the Check Component is “Checked”.



SetCheckText (Action)

This Action allows the setting of the Text of the selected Check Component.

Text: This option allows the input of the Text to be used for the Check Component. This is a String value.

SetHeight (Action)

This Action allows the setting of the Height of the selected Component.

Height: This option allows the setting of the Height [0 to 1000].



SetWidth (Action)

This Action allows the setting of the Width of the selected Component.

Width: This option allows the setting of the Width [0 to 1000]. Also, another part of the HUD Editor that has been updated in this release is that some parameters for the List Component were not displayed. This has now been rectified, as shown below:

The new options available here are:

Use mouse wheel: This option allows the use of the Mouse wheel to scroll through the List of Items, if checked. Use single selection toggling: This option allows the selection of single Items in the List, and will deselect any previously selected Item.



The new options available here are:

Scrollbar Width: This option sets the Width of the Scrollbar [0 to 100]. Arrows Height: This option sets the Height of the Arrows for the Scrollbar [0 to 100].

Finally, there are several other changes, which I won’t go through in too much detail, as they are pretty self-explanatory. These are:

It is now possible to open multiple HUDs at the same time.

It is now possible to Import one HUD into another.

It is now possible to Export a HUD as a Template.

It is now possible to Copy/Paste from one HUD to another.

There is also a new “Last Five Opened” Menu item, which will display the last five HUDs that have been opened in the HUD Editor. This can be found in the “HUD” Menu (see below).

There is now a Grid option in the Live Preview, which can be found in the “Preview” option of the “HUD” Menu:



It is now possible to use CTRL-C to copy items to the Clipboard.

The “SendEventToUser” Command now displays a list of available Handlers if a Game is open.

The “SetBackgroundImage” Command now displays a list of available Textures.

There is now “Full Screen” Movie support, with automatic aspect ratio.

There is a new “Transparency Color” for Movies (see “hud.setMovieTransparentColor” in Appendix 1)

There is also now support for the streaming of Movies & other “Live Streaming”, using the Cache (see the MoviePlayer demo in ShiVa).



Whilst not technically part of the HUD Editor, I thought I would also mention the new “Compass” system, as you will no doubt be using this with your HUDs. This new functionality is provided via the following Functions (which are explained in more detail in Appendix 1):

system.areHeadingUpdatesEnabled ( )

system.areHeadingUpdatesSupported ( )

system.enableHeadingUpdates ( )

system.getLastKnownHeading ( )

system.getLastKnownTrueHeading ( )



CHAPTER 10 – Attributed To You In this Chapter, I’ll take you through the new functionality available in the Attributes Editor. The first major addition is the ability to change the LOD parameters for Animations, as shown below:



Disabled out of frustrum: This option allows the enabling, or disabling, of the Animation when it is out of the Frustrum of the Camera. Update rate:

High res: This option allows the setting of the percentage of Animation Keys to be skipped at High Resolution [0 to 100]. Low res: This option allows the setting of the percentage of Animation Keys to be skipped at Low Resolution [0 to 100].

Screen size:

High res: This option allows the setting of the Object‘s size on the Screen at High Resolution [0 to 100]. Low res: This option allows the setting of the Object’s size on the Screen at Low Resolution [0 to 100].

Another inclusion is the ability to display the Attributes of the Active Camera:

There is one other change in this Menu, which is the ability to be able to “Lock” (“Lock on current object attributes”), or “Unlock” (“Unlock”), the current selection. The Attributes of the Active Camera can be accessed by clicking on the “Active camera attributes” option in the “Display” Menu:



The options available for the Camera are as follows:

FOV: This option allows the setting of the Field of View, in Degrees [5 to 80]. Clip min: This option allows the setting of the minimum Clipping distance [0.1 to 100]. Clip max: This option allows the setting of the maximum Clipping distance [10 to 10000]. Output: This option provides a drop-down list of all available output options for the view from the Camera. Motion blur Amount: This option allows the setting of the amount of Motion Blur to apply [0 to 1]. Velocity blur Amount: This option allows the setting of the amount of Velocity Blur to apply [0 to 1].



Depth of Field: These options allow the setting of various DOF values for the “Depth Blur” effect (i.e. the creation of a blurring of the image from the Camera):

Amount: This option allows the setting of the amount of blurring to apply [0 to 1]. Distance: This option allows the setting of the distance at which the blurring will start [0 to 9999.9]. Range: This option allows the setting of the range of the blurring [0 to 9999.9]. Focus min: This is an auto-calculated field based on “Distance” & “Range” that provides the minimum Focal distance at which blurring will start being applied [0.1 to 5000.1]. Focus max: This is an auto-calculated field based on “Distance” & “Range”, that provides the maximum Focal distance at which blurring will stop being applied [0.1 to 15000]. Focus on: This is a “picker” that allows the selection of an item in the Scene to be used as the Focus for the Camera, to determine the Depth Blur distance.

Distortion: These options allow the setting of the Distortion values, which will be applied to the image from the Camera, using a “sine-wave” model:

Amount: This option allows the setting of the amount of Distortion to apply [0 to 1]. Amplitude: This option allows the setting of the Amplitude (i.e. maximum height / depth) of the Distortion wave [0 to 1]. Frequency: This option allows the setting of the Frequency (i.e. speed) of the Distortion wave [0 to 10]. Tiling: This option allows the setting of the Tiling (i.e. number of separate areas) to be used for the Distortion [0 to 100].



Another major new feature is the ability to set Frustrum-based activation:

Frustrum activation: This option allows the setting of “Frustrum-based” activation to either on, or off, for the selected Item.

The final thing I’ll mention for the Attributes Editor, is that you can now Right-Click in the “Subsets” area of the “Shape Attributes” roll-up to open an option to edit the Material of the Subset in the Material Editor, as shown below:



That’s about all for the Attributes Editor. Next I’ll tell you about the changes to the Ambience Editor.



CHAPTER 11 – Pure Ambience In this Chapter, I’ll explain all the changes that the wonderful people at StoneTrip have made to the Ambience Editor (of which there are quite a few!). Firstly, ShiVa is now endowed with Cascaded Shadow Maps (CSM). Hang on though, what exactly are they? According to an article by Rouslan Dimitrov from nVidia Corporation, they are “a very popular technique to obtain realistic shadows in game engines”. NOTE: the full article is obtainable at the following address: http://developer.download.nvidia.com/SDK/10.5/opengl/src/cascaded_shadow_maps/doc/cascaded_shadow_maps.pdf Usually CSM are used to cast Shadows over large Terrains from a large light source (such as the Sun). However, since obtaining realistic Shadows would entail extremely detailed and hence very large Maps, Cascaded Shadow Mapping uses several Maps to automatically generate the required Shadows:

a Map that covers only nearby Objects, so that each Object casts a detailed Shadow

a Map that captures everything in the distance with coarse resolution

additional optional Maps in between the above two The ShiVa version of CSM allows for up to 4 Maps, and also Percentage Closer Filtering (PCF). NOTE: PCF is only active when all 4 CSM are in use. See Appendix 1 for the new API Constants & Functions available for CSM. All of the new Constants can be set and retrieved using the following existing ShiVa Functions: bOK = application.setOption ( kOption, nValue ) and nValue = application.getOption ( kOption ) examples: application.setOption ( application.kOptionDynamicShadowsQuality, 5 ) application.setOption ( application.kOptionTexturesQuality, 2 ) application.setOption ( application.kOptionShadersQuality, 2 ) application.setOption ( application.kOptionTerrainsQuality, 0 ) application.setOption ( application.kOptionFullscreen, 1 ) local nFullScreen = application.setOption ( application.kOptionFullscreen ) if ( nFullScreen == 0 ) then log.message ( “The application runs in a window” ) elseif ( nFullScreen == 1 ) then log.message ( “The application runs in full screen mode” ) end

http://developer.download.nvidia.com/SDK/10.5/opengl/src/cascaded_shadow_maps/doc/cascaded_shadow_maps.pdf

http://developer.download.nvidia.com/SDK/10.5/opengl/src/cascaded_shadow_maps/doc/cascaded_shadow_maps.pdf



Now that I have explained CSM, I will go through the updated Ambience Editor options, and highlight any new features as they crop up. The first roll-up is the “General” roll-up:

This roll-up has changed considerably from the one in v1.7:

1) Ambient now contains additional Colour selectors for the Shadows (for CSM). 2) Shadow has been removed as an individual heading. 3) Skybox has also been removed.



Next, we have the “PostRE” roll-up:

This roll-up has one new option:

Contrast: This option allows the setting of the “Intensity” of the Contrast to be used. The “Intensity” slider allows the setting of the Intensity *-1 to 1].



The “Lighting” and “Music” roll-ups are unchanged, so I’ll move on to the new “Sky” roll-up:

This roll-up is identical to the “Skybox” options that were originally in the “General” roll-up, so I won’t comment further.



The next roll-up introduces another wonderful new feature in ShiVa.....Oceans:

Since this roll-up (and functionality) is totally new in v1.8, I’ll explain each of the options in some detail.



This dialog allows the setting of all Parameters required by ShiVa to create Oceans including the size and frequency of Waves, the colour of both the surface of the Ocean, and the underwater “fog”, and also the Texturing of the Foam.

General

Enable ocean: This option either enables (if the check box is checked), or disables, the Ocean. Grid Size: This option allows the setting of the size of the Ocean as a number of Polygons² [8, 16, 32, 64, 128, 256]. Unit Size: This option allows the setting of the unit size (i.e. distance between Polygons) to be used by the Ocean [0.1 to 2]. Wave Tiling: This option allows the setting of the tiling (i.e. repetition) to be used for the Waves [1, 2, 4, 8, 16].

Waves

Amplitude: This option allows the setting of the maximum amplitude (i.e. height) of the Waves [0 to 8]. Frequency: This option allows the setting of the frequency with which the Waves will roll in and out [0 to 1]. Mean height: This option allows the setting of the mean height of the Waves [-10 to 10], and is useful for ensuring that the Waves are fairly consistent in appearance.

Surface

Color: This option allows the setting of the diffuse colour of the Ocean. NOTE: clicking on the coloured box will open the standard ShiVa colour dialog. Color factor: This option allows the setting of the factor by which the colour of the Ocean will be modulated with reflection [0 to 1]. Color max dist: This option allows the setting of the maximum distance at which the colour will be applied to the Ocean before full reflection [0 to 1000]. Fresnel power: This option allows the setting of the Fresnel (or near-field diffraction) power of the Ocean [2 to 16]. “Fresnel” according to Wikipedia is:

“Fresnel diffraction or near-field diffraction is a process of diffraction that occurs when a wave passes through an aperture and diffracts in the near field, causing any diffraction pattern observed to differ in size and shape, depending on the distance between the aperture and the projection.”



Fresnel bias: This option allows the setting of the bias to be used with the “Fresnel power” on the Ocean *0 to 1]. Reflection noise: This option allows the setting of the noise to be applied to the reflection of light from the Ocean [0 to 1]. Refraction noise: This option allows the setting of the noise to be applied to the refraction of light from the Ocean [0 to 1]. Tiling: This option allows the setting of the tiling to be used for the Ocean [0.1 to 4]. NOTE: tiling is a collection of Objects that fills an area with no overlaps and no gaps.

Foam Texture: These options allow the selection of the Texture to be used for any foam that is to appear on the Ocean. NOTE: the Texture to be used must already be loaded into ShiVa. Tiling: This option allows the setting of the tiling to be used for the foam to appear on the Ocean [0.1 to 4].

Underwater Fog Color: This option allows the setting of the colour of the underwater “fog” for the Ocean. NOTE: clicking on the coloured box will open the standard ShiVa colour dialog. Fog density: This option allows the setting of the density of the underwater “fog” [0 to 1].

Well, that’s it for the “Ocean” roll-up.



Below is the new “Optimisation” roll-up:

This new roll-up allows the setting of various Parameters that can be used to “tweak” the other Ambience settings.

Shadow

The options in this section all relate to CSM, and are as follows:

Clip Size: This option allows the setting of the minimum Object Shadow size of the CSM as a percentage of Screen size [0 to 100]. NOTE: this is unchanged from v1.7



Fade distance: This option allows the setting of the distance at which the CSM will start to fade out [0 to 1000]. Max distance: This option allows the setting of the distance at which the CSM will no longer be applied [0 to 1000].

PerPixelLighting Clip Size: This option allows the setting of the minimum Object size to enable PerPixel Lighting as a percentage of Screen size [0 to 100].

NormalMapping Clip Size: This option allows the setting of the minimum Object size to enable Normal Mapping as a percentage of Screen size [0 to 100]. Fade Size: This option allows the setting of the minimum Object size at which the Normal Mapping will start to fade out [0 to 100].

SpecularLighting Clip Size: This option allows the setting of the minimum Object size to enable Specular Lighting as a percentage of Screen size [0 to 100]. Fade Size: This option allows the setting of the minimum Object size at which the Specular Lighting will start to fade out [0 to 100].

Sectors These options relate to the Sectors displayed in the Scene Viewer when you select “display” -> “sector”: Cell Min H: This is the width of the Cell. [1 to 128]. Cell Min V: This is the height of the Cell. [1 to 128]. Max Depth: This is the number of Cells. [1 to 10]. Constraint to Terrain horizontal boundary: This option restricts, if checked, the Cells to fit to the Terrain dimensions.



CHAPTER 16 – Creating a Terrain In this Chapter, I’ll explain the changes to the Terrain Editor. Firstly, it is now possible to create “8x8” Chunks, in addition to the existing “16x16” & “32x32”, as shown below:

Basically, all this change means is that your Terrain Chunks can now be of a smaller size than was previously available.



Secondly, you now have the option to bake Shadows into the Terrain Texture (This option can be found in the “Edit” Menu):

Choosing this option will speed up the rendering of the Terrain, as all of the Shadows relating to the Terrain will have been pre-computed, and “baked” into the Terrain Texture.



The third change is in the “Materials” roll-up:

There are two new options in this roll-up:

AO Amount: This option allows the setting of the amount of Ambient Occlusion to be applied to the Terrain [0 to 1]. AO Distance: This option allows the setting of the distance at which Ambient Occlusion will be applied to the Terrain [0 to 100].



Finally, I’ll quickly mention the “Roads” roll-up, as I think I missed it in the original Book!:

This roll-up only has three options:

Name: This option allows the setting of the name to be used for this Road. Inner width: This option allows the setting of the inner width of the Road [0 to 50]. Outer width: This option allows the setting of the outer width of the Road [0 to 50].

The selection of different values for the “Inner width” and “Outer width” parameters will cause the Road to have a distinct “verge” along the edge, as the “Outer width” parameter determines the fade distance for the Road. Well, that’s it for the Terrain Editor, so I’ll now move on to the Game Editor updates.



CHAPTER 18 – THE GAME EDITOR & THE SCENE VIEWER In this Chapter I’ll quickly explain the changes to the Game Editor, and the Scene Viewer.

GAME EDITOR The first improvement that I will mention is that double-clicking on a Resource now opens it in the relevant Editor (where applicable). This update has also added several new options / abilities to the Environment tab:

If the Game is currently not running, this tab will display the initial values of the Environment Variables that will be used at the start of the Game. If the Game is running, however, this tab will display the actual “run-time” values of these Variables. Also, these Variables can be modified whilst the Game is running, which will help in fine tuning Applications. The final thing that has changed for this tab is that it now has a “Fast Filter” to assist in searching for a specific Variable when there is a large number of them. The Game Editor also has a “Last Five Opened” Menu, as shown below:



SCENE VIEWER Whilst not strictly part of the Scene Viewer, I thought I’d start by mentioning the new “Iterations per Step” parameter for the Physics System (see Appendix 1 for the relevant SCENE API Functions, “setDynamicsIterationsPerStep” & “getDynamicsIterationsPerStep”): Basically, this option allows you to set the number of iterations that the Physics system will perform per step. Increasing this number will give a more accurate Physics system, but will obviously mean that it will be slower, as it is having to do more calculations for each step. NOTE: the ShiVa default is 10 iterations per step. Finally, there is also a pop-up (which I don’t think was mentioned in the Book) that allows you to set the Render Settings for the Scene:

This pop-up has the following options:

3D Device Driver: This option allows the setting of which device driver to use for the rendering of the Scene. The options available are pretty self-explanatory, and are:

0. Software – The Graphics Card is not used. 1. Hardware – Approximates a Graphics Card without Vertex or Pixel Shaders. 2. Hardware – High Quality – Uses all available capabilities of the Graphics Card.

Use vertex shaders: This option allows the selection of whether to use Vertex Shaders, or not. Use pixel shaders: This option allows the selection of whether to use Pixel Shaders, or not.



Textures quality: This option allows the selection of the quality of the Textures, and can be one of the following:

0: No Anisotropic filtering 1: 2x Anisotropic filtering 2: 4x Anisotropic filtering 3: 8x Anisotropic filtering 4: 16x Anisotropic filtering

Terrains quality: This option allows the selection of the quality of the Terrain, and can be one of the following:

0: Lowest 1: Low 2: Medium 3: High 4: Highest

The next Section determines the various options for the Shadows system.

Buffer count: This option allows the selection of the number of Buffers to be used for Shadows [1 to 4] Buffer size: This option allows the selection of the size of the Buffers, in Bytes, [128|256|512|1024]. Screen Space blur: This option allows the selection of whether to use Screen Space Blur, or not. PCF Sample count: This option allows the selection of the number of PCF Samples to be used [0|4|8]. Constant sampling: This option allows the selection of whether to constantly sample, or not.

The final Section allows the setting of options for the Monitor itself:

Use monitor vertical synchronisation: This option allows the selection of whether to use the Monitor’s Vertical refresh as a Synchronising factor, or not. Viewport rotation: This option allows the selection of the rotation of the Viewport, and can be one of the following:

0: None 1: -90° 2: 180° 3: +90°



CHAPTER 19 – THE DATA EXPLORER In this Chapter, I’ll update you on the changes made to the Data Explorer: The first of these is the ability to create “128x128” RenderMaps, as shown below:

Another major change is that you can now use the “F2” key to rename a File. By selecting a File, and then pressing “F2”, you will be presented with the following:

Whilst on the subject of the Data Explorer, I thought I would just give you some screenshots of the various options available. The first Menu is pretty straightforward, in that it allows you to “Open”, “Rename”, “Duplicate” and “Delete” a selected Resource:



The second Menu is again straightforward, and allows you to change various display options for the Data Explorer, such as showing “Thumbnails”, or “Details”, sorting, refreshing the view etc.:

The third Menu is slightly more complex, in that it has Sub-Menus for “Model” & “Resource”, but should be easy to understand. The Sub-Menu for “Model” is shown below:

Note that there is a new option in v1.8 for this menu that allows you to make the selected Model a “Projector” (either an Orthographic Projector, or a Perspective Projector). According to http://www.wordiq.com/definition/Orthographic_projection

“Orthographic projection is a means of representing a three-dimensional object in two

dimensions. It uses multiple views of the object, from points of view rotated about the object's center through increments of 90 degrees. Equivalently, the views may be considered to be obtained by rotating the object about its center through increments of 90 degrees. The views are positioned relative to each other according to either of two schemes: first-angle or third-angle projection. In each, the appearances of views may be thought of as being

projected onto planes that form a transparent "box" around the object.”

According to http://www.wordiq.com/definition/Perspective_projection

“Perspective projection is a type of drawing that graphically approximates on a planar (two-

dimensional) surface (e.g. paper) the images of three-dimensional objects so as to approximate actual visual perception. It is sometimes also called perspective view or perspective drawing or simply perspective. A perspective projection drawing must be made according to an

established geometric protocol.”

http://www.wordiq.com/definition/Orthographic_projection

http://www.wordiq.com/definition/Dimension

http://www.wordiq.com/definition/Orthographic_projection



Selecting the “Projector” option in this Menu opens the following dialog:

The Sub-Menu for “Resource” has also changed, to allow you to create a “PixelMap”, as shown below:

“PixelMaps” are a means of recording data (such as colour and intensity) for every pixel that makes up an image, and are usually used for drawing/painting type applications, which allow the user to create artwork on the screen in the same way as if they were drawing/painting on paper or canvas.

Selecting “PixelMap” in this Menu opens the following dialog:



The options available for this dialog are:

Texture width: This option allows the setting of the Width of the PixelMap Texture, in Bytes, [16|32|64|128|256|512|1024]. Texture height: This option allows the setting of the Height of the PixelMap Texture, in Bytes, [16|32|64|128|256|512|1024]. PixelMap name: This option allows the setting of the name to be used for the PixelMap.

The “Font” option, of this Menu, also has a new Parameter that allows you to select the type of the Font (including a new “Numeric Only” Font especially for HUDs):

The options available for this dialog are:

Input system font: This drop-down lists all available System Fonts, and the Button will open a standard OS search dialog, to allow new Fonts to be loaded. Font type: This option allows the selection of the type of the Font [ASCII or Numeric Only]. Texture size: This option allows the setting of the size of the Textures to be used for the Font, in Bytes [64|256|512|1024]. Blur passes: This option allows the selection of the number of Blur Passes to be carried out on the Font [0 to 4]. Font name: This option allows the setting of the name to be used for the Font.



The last, but by no means least, thing that I will mention here is that the following improvements have been made to the various “Import” & “Export” options:

“.dae” Models are now imported with their Znear, Zfar & Yfov Parameters, where these are specified in the File

You can also now import “.dwf” Models - ** A MAJOR NEW MODEL TYPE FOR SHIVA **

You can also now import “.mp4” Files for Movies The .dwf Model format is (according to Wikipedia):

“a secure file format developed by Autodesk for the efficient distribution and communication of rich design data to anyone who needs to view, review, or print design files. Because DWF files are highly compressed, they are smaller and faster to transmit than design files, without the overhead associated with complex CAD drawings (or the management of external links and dependencies). With DWF functionality, publishers of design data can limit the specific design data and plot styles to only what they want recipients to see and can publish multisheet drawing sets from multiple AutoCAD drawings in a single DWF file. They can also publish 3D models from most Autodesk design applications.”

Well, that’s it for the Data Explorer, now it’s time for the changes to the AIModel Editor.



CHAPTER 20 – THE AIMODEL EDITOR In this Chapter, I’ll explain the new functionality in the AIModel Editor. Firstly, your Functions & States can now begin with the underscore (“_”) character, as shown below:

Also, in what I personally think is a major improvement, you can now change the name of a Function etc., and ShiVa will propagate the name change through all of your Scripts (if you want!). When you make a change to a name, ShiVa will display the following dialog, which will allow you to decide whether you want the change to be propagated, or not:

Obviously, selecting “Yes” will propagate the change, and selecting “No” won’t.



Another update to the AIModel Editor is extremely handy if you use xml Variables, as you can now default the initial value of an xml Variable by importing an xml File, as shown below:

To import an xml File, click on the ( ) button next to the “Init Value” heading, and this will open a standard OS search dialog box, allowing you to select the relevant xml File to use for the “Initial Value”. Also, there is a new predefined Handler called “onApplicationWillQuit”. This Handler runs when a “Quit” command is issued to the application. So, you can now put all of your clean-up, auto-save etc. Code in this Handler to ensure that it runs before the application closes:



The last couple of changes to the AIModel Editor are that there is now a list of the last five opened AIModels in the “AIModel” Menu:

And finally, “CTRL-C” can now be used to copy Variables, Handlers etc. to the Clipboard Well, that’s about it for the AIModel Editor, so I’ll now move on to the Script Editor updates.



CHAPTER 21 – THE SCRIPT EDITOR The Script Editor has been improved to provide more descriptive “run-time” Error messages. Not too much that I can say about that. I just hope that, if you do come across one of the new “run-time” Error messages, they’ll help you to quickly pick up where the Error is, and how to correct it!



CHAPTER 22 – OTHER CHANGES In this Chapter, I’ll go through the other changes in v1.8 that didn’t seem to fit into a previous Chapter. The changes are:

1. Both ODE (the Physics Engine) and VORBIS (the Sound Engine) have been updated to the latest versions, so we should be seeing some more functionality from these two in the next ShiVa updates.

2. The xml.receive Function now has optional Header parameters (see Appendix 1 for more info).

3. The scene.createRuntime Object Function now creates a “dummy” Object if the Model name is passed as “”.

4. There is a new “Virtual” Mouse that can be used when using the Wiimote as an interface device (see below).

5. ShiVa now has a Server built-in for all those multiplayer games that you want to build (see below).

6. ShiVa also now has VOIP (“Voice Over Internet Protocol” for those that don’t know!) capabilities built-in (see below).

7. All dialogs now propose the best option, according to the selection in the Scene of the opened Game.

8. When using saving and overwriting dialogs, there is now a global confirmation per Resource type.

9. CTRL-O displays open dialogs. Virtual Mouse The new “Virtual Mouse” has been developed especially for use with the Wiimote. Basically, this allows the Wiimote to take the place of the standard Mouse, and as such, can be used to remove the necessity of the User being tied to a desk, allowing for more interactivity between the User and the application. For more information, see the “VirtualMouse” Functions in the INPUT API as detailed in Appendix 1. Built-in Server StoneTrip have now included a Server built into the ShiVa Editor. This is a cut-down version of StonServer, and will allow you to create multi-player games without having to purchase a separate Server. For more information, see the “SERVER” API. As this is meant to be a Beginner's Guide to ShiVa, I won't be going into any more detail on the in-built Server. If you want to find out more, I suggest that you take a look at the Website and, more specifically, the Developers Forum.



VOIP The new VOIP functionality has been included in ShiVa to complement the new Server functionality, allowing you to create on-line games where your Users can actually talk to each other using a headset (or a microphone & speakers of course!). The new VOIP system is built around a Diffusion (or Broadcast) List. This works using the new “Diffusion” Functions in the MICROPHONE API, as detailed in Appendix 1. This functionality basically works by keeping a record of all Users that have been added to the list, and then by transmitting the relevant speech to each of them. Obviously, it is possible to set up lists which can be tailored by adding (or removing) Users depending on what type of communication is required. Again, as this is a Beginner's Guide, I won't be going into any more detail.



APPENDIX 1 – NEW API FUNCTIONS & CONSTANTS In this Appendix, I’ll run through the new (for v1.8) API Functions and Constants. NOTE: Where the “∞” symbol appears it means a number that fits within 32bit Floating Point limits.

ANIMATION

bOK = animation.setPlaybackIgnoreIfCursorOutOfRange ( hObject, nBlendLayer, bIgnore )

Call this Function to ensure that the Model will remain at its current Frame (“bIgnore = “True”) in the specified Blend Layer (by the “nBlendLayer” parameter – a zero-based numeric value) of the specified Object (by the “hObject” parameter) if the Animation Cursor is out of range (i.e. beyond either end of the Animation range). This Function returns a value of “True” if the Playback is ignored successfully, or “False” otherwise.

bIgnore = animation.getPlaybackIgnoreIfCursorOutOfRange ( hObject, nBlendLayer )

Call this Function to know if the Animation Cursor of the specified Blend Layer (by the “nBlendLayer” parameter – a zero-based numeric value) of the Animation of the specified Object (by the “hObject” parameter) is out of range (i.e. beyond either end of the Animation range). This Function returns a value of “True” if the Cursor is out of range, or “False” otherwise.

APPLICATION

application.kOptionAudioMasterVolume

This Constant holds a numeric value (between 0 & 100) denoting the current Master Volume

for the Audio system. This applies to Music, Movies & Sounds.

application.kOptionAutomaticVirtualKeyboard

This Constant holds a value of 0 or 1, to denote whether a “virtual onscreen keyboard” (for

devices that have one, such as the iPhone & PSP) will appear (1), or disappear(0)

automatically when a HUD Edit Component gains (or loses) focus.

application.kOptionFullscreenHeight

This Constant holds a numeric value (in Pixels) denoting the Full Screen Height of the current

Application Window.

application.kOptionFullscreenWidth

This Constant holds a numeric value (in Pixels) denoting the Full Screen Width of the current

Application Window.



application.kOptionHardwareOcclusion

This Constant denotes whether your computer’s graphics card can perform Hardware

Occlusion:

“Occlusion” (according to Wikipedia) is the manner in which an Object closer to the

Viewport masks (or occludes) an Object further away from the Viewport. Basically, this

means that a check can be made to see if an Object is visible and, if not, stop it from

being rendered and thus speed up the rendering of the Scene. Obviously, using the

graphics card to carry out this task will make the application run faster (i.e. more

Frames per Second) than using the CPU, as the CPU can then concentrate on other

things (such as the AI etc.).

application.kOptionDynamicShadowsBufferCount

This Constant holds a numeric value (between 1 & 4) denoting the number of Cascades in

use for the Dynamic Shadows buffer.

application.kOptionDynamicShadowsBufferSize

This Constant holds a numeric value (in Pixels - for example, 64, 128, 256, 512, 1024)

denoting the size of the Cascades in use for the Dynamic Shadows buffer.

application.kOptionDynamicShadowsScreenSpaceBlur

This Constant holds a numeric value (0 = disabled, 1 = enabled) indicating whether

ScreenSpace Blur is enabled, or not, for Dynamic Shadows.

application.kOptionDynamicShadowsPCFSampleCount

This Constant holds a numeric value (4 = 16 Samples, 8 = 32 Samples) denoting the counter

for PCF Samples for Dynamic Shadows.

application.kOptionDynamicShadowsConstantSampling

This Constant holds a numeric value (0 = disabled, 1 = enabled) indicating whether Sampling

for Dynamic Shadows is carried out whilst the application is running, or not.

NOTE: activating this option reduces flickering of the Dynamic Shadows, but will also impact

on the Frame rate.



bOK = application.resetAverageFrameTime ( nSampleCount )

Call this Function to reset he Average Frame Time using a specified number of Samples (by

the “nSampleCount” parameter – a numeric value denoting the number of Samples to use).

This Function returns “True” if the Frame Time is reset successfully, or “False” otherwise.

nStatus = application.getCurrentUserScenePreloadingStatus ( )

Call this Function to obtain the current Preloading Status of the current User Scene. This

Function returns a numeric value (between 0 & 1 – “0” = not loaded at all, “1” = fully

loaded). Note that a return value of less than 0 indicates that errors have occurred in loading

the Scene.

example:

if ( application.getCurrentUserScenePreloadingStatus == 1)

then

application.setCurrentUserScene ( “myScene” )

end

sDirectory = application.getPackDirectory ( )

Call this Function to obtain the absolute path of your Application. This Function returns a

String (“sDirectory”) containing the path of the Application.

example:

local sURI = “file://”..application.getPackDirectory ( )..”/game.stk”

if ( not system.isInstalled ( sURI )

then

system.install ( u )

end

bYes = application.isOverlayMoviePlaying ( )

Call this Function to know if an Overlay Movie is currently playing. This Function returns

"True" if then Overlay Movie is currently playing, or “false” otherwise.

bOK = application.playOverlayExternalMovie ( sPath )

Call this Function to play a specified external Movie File (by the “sPath” parameter – a string

value denoting the location of the external File) as an Overlay above your application. This

Function returns “True” if the specified Movie File begins to play successfully, or “False”

otherwise.



bOK = application.playOverlayMovie ( sName )

Call this Function to play a specified Movie File (by the “sName” parameter – a string value

denoting the Name of the Movie that has been preloaded into ShiVa) as an Overlay above

your application. This Function returns “True” if the specified Movie File begins to play

successfully, or “False” otherwise.

bOK = application.resetTotalFrameTime ( nInitialTime )

Call this Function to reset the Total Frame Time to a specified value (by the “nInitialTime”

parameter – a numeric value between 0 & ∞). This Function returns “True” if the Total

Frame Time is successfully reset, or “False” otherwise.

bOK = application.startCurrentUserScenePreloading ( sName )

Call this Function to start preloading of a specified Scene (by the “sName” parameter – a

string value). This Function returns “True” if preloading of the Scene is started successfully,

or “False” otherwise. Note that the specified Scene must already be declared in the Game

Editor.

example:

application.startCurrentUserScenePreloading ( “myScene” )

bOK = application.stopOverlayMovie ( )

Call this Function to stop an Overlay Movie from playing. This Function returns “True” if the

Overlay Movie is stopped successfully, or “False” otherwise.

bYes = application.mightBeCracked ( )

Call this Function to perform some tests on the application, to determine if it might have

been “cracked”. This Function returns “True” if the application appears to have been

“cracked”, or “False” otherwise.

NOTE: This Function is currently only implemented for the iPhone.



CACHE

bOK = cache.addStreamFile ( sFileName, sFileURI )

Call this Function to add a specified “Stream File” (by the “sFileName” parameter – a string

value) from a specified location (by the “sFileURI” parameter – a string value) to the Cache.

This Function returns a value of “True” if the File is successfully added to the Cache, or

“False” otherwise.

bOK = cache.removeFile ( sFileName )

Call this Function to remove a specified File (by the “sFileName” parameter – a string value)

from the Cache. This Function returns a value of “True” if the specified File is successfully

removed from the Cache, or “False” otherwise.

CAMERA

bOK = camera.setDepthBlurFactor ( hObject, nValue )

Call this Function to set the Depth Blur Factor (by the “nValue” parameter, a numeric value

between 0 & 1 - “0” denotes no Depth Blur, and “1” denotes maximum Depth Blur) of a

specified Camera (by the “hObject” parameter). This Function returns a value of “True” if the

Depth Blur Factor is set successfully, or “False” otherwise.

example:

-- This sample creates a progressive Depth Blur

local hCamera = application.getCurrentUserActiveCamera ( )

local nCurrentFactor = camera.getDepthBlurFactor ( hCamera )

local nNewFactor = math.min ( nCurrentFactor + application.getLastFrameTime ( ), 1 )

camera.setDepthBlurFactor ( hCamera, nNewFactor )



bOK = camera.setDepthBlurFocusRangeMax ( hObject, nValue )

Call this Function to set the maximum value (by the “nValue” parameter – a numeric value

between 0.1 & 1500) at which blurring won’t occur for a specified Camera (by the “hObject”

parameter). This Function returns a value of “True” if the maximum Depth Blur range is set


example:

-- Objects that are between 0.5 and 7 units from the Camera won’t be blurred


camera.setDepthBlurFocusRangeMin ( hCamera, 0.5 )

camera.setDepthBlurFocusRangeMax ( hCamera, 7 )

bOK = camera.setDepthBlurFocusRangeMin ( hObject, nValue )

Call this Function to set the minimum value (by the “nValue” parameter – a numeric value

between 0.1 & 1000) at which blurring won’t occur for a specified Camera (by the “hObject”

parameter). This Function returns a value of “True” if the minimum Depth Blur range is set


example:

-- Objects that are between 0.5 and 7 units from the Camera won’t be blurred


camera.setDepthBlurFocusRangeMin ( hCamera, 0.5 )

camera.setDepthBlurFocusRangeMax ( hCamera, 7 )

bOK = camera.setDistortionAmplitude ( hObject, nValue )

Call this Function to set a specified Distortion Amplitude (by the “nValue” parameter – a

numeric value between 0 & 1) for a specified Camera (by the “hObject” parameter). This

Function returns a value of “True” if the minimum Distortion Amplitude is set successfully, or


example:


camera.setDistortionFactor ( hCamera, 1 )

camera.setDistortionAmplitude ( hCamera, 0.1 )

camera.setDistortionFrequency ( hCamera, 0.1 )

camera.setDistortionTiling ( hCamera, 15 )



bOK = camera.setDistortionFactor ( hObject, nValue )

Call this Function to set a specified Distortion Factor (by the “nValue” parameter – a numeric

value between 0 & 1) for a specified Camera (by the “hObject” parameter). This Function

returns a value of “True” if the minimum Distortion Factor is set successfully, or “False”

otherwise.

example:






bOK = camera.setDistortionFrequency ( hObject, nValue )

Call this Function to set a specified Distortion Frequency (by the “nValue” parameter – a


Function returns a value of “True” if the minimum Distortion Frequency is set successfully, or


example:






bOK = camera.setDistortionTiling ( hObject, nValue )

Call this Function to set a specified Distortion Tiling (by the “nValue” parameter – a numeric

value between 0 & 100) for a specified Camera (by the “hObject” parameter). This Function

returns a value of “True” if the Distortion Tiling is set successfully, or “False” otherwise.

example:








nValue = camera.getDistortionTiling ( hObject )

Call this Function to obtain the current value of the Distortion Tiling for a specified Camera

(by the “hObject” parameter). This Function returns a numeric value (between 0 & 100).

example:


local nFactor = camera.getDistortionFactor ( hCamera )

local nAmplitude = camera.getDistortionAmplitude ( hCamera )

local nFrequency = camera.getDistortionFrequency ( hCamera )

local nTiling = camera.getDistortionTiling ( hCamera )

log.message ( “Distortion Factor : “, nFactor )

log.message ( “Distortion Amplitude : “, nAmplitude )

log.message ( “Distortion Frequency : “, nFrequency )

log.message ( “Distortion Tiling : “, nTiling )

nValue = camera.getDistortionFrequency ( hObject )

Call this Function to obtain the current value of the Distortion Frequency for a specified

Camera (by the “hObject” parameter). This Function returns a numeric value (between 0 &

10).

example:












nValue = camera.getDistortionFactor ( hObject )

Call this Function to obtain the current value of the Distortion Factor for a specified Camera


example:










nValue = camera.getDistortionAmplitude ( hObject )

Call this Function to obtain the current value of the Distortion Amplitude for a specified


1).

example:












nValue = camera.getDepthBlurFocusRangeMin ( hObject )

Call this Function to obtain the current value of the minimum Depth Blur Focus range for a

specified Camera (by the “hObject” parameter). This Function returns a numeric value

(between 0.1 & 1000).

example:


local nMin = camera.getDepthBlurFocusRangeMin ( hCamera )

local nMax = camera. getDepthBlurFocusRangeMax ( hCamera )

local nFactor = camera.get getDepthBlurFactor ( hCamera )

log.message ( “Depth Blur Focus Range Minimum : “, nMin )

log.message ( “Depth Blur Focus Range Maximum : “, nMax )

log.message ( “Depth Blur Factor : “, nFactor )

nValue = camera.getDepthBlurFocusRangeMax ( hObject )

Call this Function to obtain the current value of the maximum Depth Blur Focus range for a

specified Camera (by the “hObject” parameter). This Function returns a numeric value

(between 0.1 & 1500).

example:










nValue = camera.getDepthBlurFactor ( hObject )

Call this Function to obtain the current value of the Depth Blur Factor for a specified Camera


example:








bOK = camera.setVelocityBlurFactor ( hObject, nValue )

Call this Function to set a specified Velocity Blur Factor (by the “nValue” parameter – a


Function returns a value of “True” if the Velocity Blur Factor is set successfully, or “False”

otherwise.

example:


camera.setVelocityBlurFactor ( hCamera, 1 )

nValue = camera.getVelocityBlurFactor ( hObject )

Call this Function to obtain the current value of the Velocity Blur Factor for a specified


1).

example:


local nFactor = camera.get getVelocityBlurFactor ( hCamera )

log.message ( “Velocity Blur Factor : “, nFactor )



DEBUG

nBytes = debug.getTotalMemoryUsed ( )

Call this Function to obtain the total amount of Memory (in Bytes) used by your Application.

This Function returns a numeric value (in Bytes).

HUD

bChecked = hud.getCheckState ( hComponent )

Call this Function to obtain the current state of a specified Check Box Component (by the

“hComponent” parameter). This Function returns a value of “True” if the Check Box

Component is checked, or “False” otherwise.

hContainer = hud.getComponentContainer ( hComponent )

Call this Function to obtain the Parent Container of a specified Component (by the

“hComponent” parameter). This Function returns the Handle of the Parent Container, or

“Nil” if the Component has no Parent Container.

nProgress = hud.getMovieBufferingProgress ( hComponent )

Call this Function to obtain the current Buffering Progress value of the Movie currently being

buffered (by the “hComponent” parameter). This Function returns a numeric value (between

0 & 255).

hPixelMap = hud.getPixelMap ( hComponent )

Call this Function to obtain the PixelMap of a specified Component (by the “hComponent”

parameter). This Function returns the Handle of the PixelMap, or “Nil” if the Component has

no PixelMap.

bOK = hud.matchComponentScreenSpaceBottomLeftCorner ( hComponent,

hOtherComponent )

Call this Function to set the Bottom Left Corner of the second object (by the

“hOtherComponent” parameter) match the Bottom Left Corner of the first Component (by

the “hComponent” parameter). This Function returns a value of “True” if the match is

completed successfully, or “False” otherwise.



bOK = hud.matchComponentScreenSpaceBottomRightCorner ( hComponent,

hOtherComponent )

Call this Function to set the Bottom Right Corner of the second object (by the

“hOtherComponent” parameter) match the Bottom Right Corner of the first Component (by



bOK = hud.matchComponentScreenSpaceCenter( hComponent, hOtherComponent )

Call this Function to set the Centre of the second object (by the “hOtherComponent”

parameter) match the Centre of the first Component (by the “hComponent” parameter).

This Function returns a value of “True” if the match is completed successfully, or “False”

otherwise.

bOK = hud.matchComponentScreenSpaceTopLeftCorner( hComponent,

hOtherComponent )

Call this Function to set the Top Left Corner of the second object (by the

“hOtherComponent” parameter) match the Top Left Corner of the first Component (by the

“hComponent” parameter). This Function returns a value of “True” if the match is completed


bOK = hud.matchComponentScreenSpaceTopRightCorner( hComponent,

hOtherComponent )

Call this Function to set the Top Right Corner of the second specified Component (by the

“hOtherComponent” parameter) match the Top Right Corner of the first specified

Component (by the “hComponent” parameter). This Function returns a value of “True” if the

match is completed successfully, or “False” otherwise.

bOK = hud.setButtonTextLineSpacing ( hComponent, nSpacing )

Call this Function to set the Text Line Spacing (by the “nSpacing” parameter – a numeric

value between 0 & 100, which denotes the height of the Text Line Spacing as a percentage of

the height of the Button Component) of a specified Button Component (by the

“hComponent” parameter). This Function returns a value of “True” if the Text Line Spacing is

set successfully, or “False” otherwise.

bOK = hud.setCheckFont ( hComponent, sFontName )

Call this Function to set the Font (by the “sFontName” parameter – a string value denoting

the preloaded Font) of a specified Check Component (by the “hComponent” parameter).

This Function returns a value of “True” if the Font is set successfully, or “False” otherwise.



bOK = hud.setCheckIcons ( hComponent, sCheckedIconName, sUncheckedIconName )

Call this Function to set the Checked Icon (by the “sCheckedIcon” parameter – a string value

denoting the preloaded Icon graphic) and the Unchecked Icon (by the “sUncheckedIcon”

parameter – a string value denoting the preloaded Icon graphic) of a specified Check


Icons are set successfully, or “False” otherwise.

bOK = hud.setCheckOnCheckedAction ( hComponent, hAction )

Call this Function to set the Action (by the “hAction” parameter – a predefined HUD Action)

to be called when a specified Check Component (by the “hComponent” parameter) is

“Checked”. This Function returns a value of “True” if the Action is set successfully, or “False”

otherwise.

bOK = hud.setCheckOnUncheckedAction ( hComponent, hAction )

Call this Function to set the Action (by the “hAction” parameter – a predefined HUD Action)

to be called when a specified Check Component (by the “hComponent” parameter) is

“Unchecked”. This Function returns a value of “True” if the Action is set successfully, or


bOK = hud.setCheckState ( hComponent )

Call this Function to set the State of a specified Check Component (by the “hComponent”

parameter). This Function returns a value of “True” if the State is set successfully, or “False”

otherwise. Note that using this Function will alternate the State of the Check Component

between “Checked” and “Unchecked”.

bOK = hud.setCheckText ( hComponent, sText )

Call this Function to set the Text (by the “sText” parameter – a string value) of a specified

Check Component (by the “hComponent” parameter). This Function returns a value of

“True” if the Text is set successfully, or “False” otherwise.

bOK = hud.setCheckTextAlignment ( hComponent, kHAlignment, kVAlignment )

Call this Function to set the Horizontal Alignment (by the “kHAlignment” parameter – one of

the standard Horizontal “Alignment” Constants) and the Vertical Alignment (by the

“kVAlignment” parameter – one of the standard Vertical “Alignment” Constants) of the Text

of a specified Check Component (by the “hComponent” parameter). This Function returns a

value of “True” if the Text Alignment is set successfully, or “False” otherwise.



bOK = hud.setCheckTextCase ( hComponent, kCase )

Call this Function to set the Case (by the “kCase” parameter – one of the standard “Case”

Constants) of the Text of a specified Check Component (by the “hComponent” parameter).

This Function returns a value of “True” if the Case of the Text is set successfully, or “False”

otherwise.

bOK = hud.setCheckTextHeight ( hComponent, nTextHeight )

Call this Function to set the Text Height (by the “nTextHeight” parameter – a numeric value

between 0 & 100, which denotes the height of the Text as a percentage of the height of the

Check Component) of a specified Check Component (by the “hComponent” parameter). This

Function returns a value of “True” if the Text Height is set successfully, or “False” otherwise.

bOK = hud.setCheckTextLetterSpacing ( hComponent, nSpacing )

Call this Function to set the Text Letter Spacing (by the “nSpacing” parameter – a numeric

value between 0 & 100, which denotes the spacing of the Text as a percentage of the height

of the Check Component) of a specified Check Component (by the “hComponent”

parameter). This Function returns a value of “True” if the Text Letter Spacing is set


bOK = hud.setCheckTextLineSpacing ( hComponent, nSpacing )



of the Check Component) of a specified Check Component (by the “hComponent”

parameter). This Function returns a value of “True” if the Text Line Spacing is set


bOK = hud.setComponentBlendMode ( hComponent, kBlendMode )

Call this Function to set a specified Blend Mode (by the “kBlendMode” parameter, which

must be one of the Blend Mode Constants – “hud.kBlendModeAdd”,

“hud.kBlendModeDefault” or “hud.kBlendModeModulate”) of a specified Component (by



bOK = hud.setEditTextLineSpacing ( hComponent, nSpacing )



of the Edit Component) of a specified Edit Component (by the “hComponent” parameter).

This Function returns a value of “True” if the Text Line Spacing is set successfully, or “False”

otherwise.



bOK = hud.setLabelTextLineSpacing ( hComponent, nSpacing )



of the Label Component) of a specified Edit Component (by the “hComponent” parameter).


otherwise.

bOK = hud.setListTextLineSpacing ( hComponent, nSpacing )



of the List Component) of a specified Edit Component (by the “hComponent” parameter).


otherwise.

bOK = hud.setMovieTransparentColor ( hComponent, nRed, nGreen, nBlue, nTolerance

)

Call this Function to set a specified Transparency Colour (by the “nRed”, “nGreen” & “nBlue”

parameters – numeric values between 0 & 255) with a specified Tolerance (by the

“nTolerance” parameter – a numeric value between 0 & 255) of a specified Movie


Movie Transparency Colour is set successfully, or “False” otherwise.

bOK = hud.setPixelMap ( hComponent, sPixelMap )

Call this Function to set a specified PixelMap (by the “sPixelMap” parameter – a string, which

denotes a PixelMap that has been preloaded into ShiVa) on a specified Component (by the

“hComponent” parameter). This Function returns a value of “True” if the PixelMap is set


sText = hud.getLabelText ( hComponent )

Call this Function to obtain the Text of a specified Label Component (by the “hComponent”

parameter). This Function returns a string value containing the Text of the Label Component.

nIndex = hud.getUnderCursorListItem ( hUser )

Call this Function to obtain the Index of the Item of the List Component of a specified User

(by the “hUser” parameter) that is currently under the Cursor. This Function returns a zerp-

based numeric value denoting the Item.



hud.kBlendModeAdd

This Constant holds a boolean value denoting whether Additive is being used as the Blend

mode, or not.

hud.kBlendModeDefault

This Constant holds a boolean value denoting whether Default is being used as the Blend

mode, or not.

hud.kBlendModeModulate

This Constant holds a boolean value denoting whether Modulate is being used as the Blend

mode, or not.

hud.kCommandTypeCopyCheckStateToRegister

This Constant denotes a CopyCheckStateToRegister Command.

hud.kCommandTypeCopyEditTextToRegister

This Constant denotes a CopyEditTextToRegister Command.

hud.kCommandTypeCopyListItemTextToRegister

This Constant denotes a CopyListItemTextToRegister Command.

hud.kCommandTypeCopyListLastSelectedItemToRegister

This Constant denotes a CopyListLastSelectedItemToRegister Command.

hud.kCommandTypeCopyTagToRegister

This Constant denotes a CopyTagToRegister Command.

hud.kCommandTypeInterpolateHeight

This Constant denotes a InterpolateHeight Command.

hud.kCommandTypeInterpolateWidth

This Constant denotes a InterpolateWidth Command.



hud.kCommandTypeMatchScreenSpaceBottomLeftCorner

This Constant denotes a MatchScreenSpaceBottomLeftCorner Command.

hud.kCommandTypeMatchScreenSpaceBottomRightCorner

This Constant denotes a MatchScreenSpaceBottomRightCorner Command.

hud.kCommandTypeMatchScreenSpaceCenter

This Constant denotes a MatchScreenSpaceCenter Command.

hud.kCommandTypeMatchScreenSpaceHeight

This Constant denotes a MatchScreenSpaceHeight Command.

hud.kCommandTypeMatchScreenSpaceTopLeftCorner

This Constant denotes a MatchScreenSpaceTopLeftCorner Command.

hud.kCommandTypeMatchScreenSpaceTopRightCorner

This Constant denotes a MatchScreenSpaceTopRightCorner Command.

hud.kCommandTypeMatchScreenSpaceWidth

This Constant denotes a MatchScreenSpaceWidth Command.

hud.kCommandTypeSetCheckState

This Constant denotes a SetCheckState Command.

hud.kCommandTypeSetCheckText

This Constant denotes a SetCheckText Command.

hud.kCommandTypeSetHeight

This Constant denotes a SetHeight Command.

hud.kCommandTypeSetWidth

This Constant denotes a SetWidth Command.



hud.kComponentTypeCheck

This Constant denotes a Check Component.

hud.kComponentTypePixelMap

This Constant denotes a PixelMap Component.

hud.kRuntimeValueRegister0

This Constant denotes the value of HUD Runtime Register #0.







INPUT

bOK = input.enableVirtualMouse ( hUser, bEnable )

Call this Function to enable/disable (by the “bEnable” parameter – a boolean value) the

Virtual Mouse for use with the Wiimote for a specified User (by the “hUser” parameter). This

Function returns a value of “True” if the Virtual Mouse is enabled successfully, or “False”

otherwise.

bOK = input.setVirtualMousePosition ( hUser, nX, nY )

Call this Function to set a specified initial position of the Virtual Mouse (by the “nX” & “nY”

parameters – numeric values in Pixels) for a specified User (by the “hUser” parameter). This

Function returns a value of “True” if the initial position is set successfully, or “False”

otherwise.



bOK = input.setVirtualMouseButtonDown ( hUser, nButton, bDown )

Call this Function to set the state of specified Button (by the “nButton” parameter – a zero-

based numeric value) to either “Up” (if the “bDown” parameter is “False”), or “Down” (if the

“bDown” parameter is “True”). This Function returns a value of “True” if the state is set


MATH

nResult = math.atan2 ( nValue1, nValue2 )

Call this Function to obtain the result of the mathematical atan2 Function, using the two

specified values (by the “nValue1” & “nValue2” parameters – numeric values between -∞ &

∞). This Function returns the angle (in Degrees) between the two parameters, putting the

result into the correct quadrant. For more information on the atan2 function, I would

suggest looking it up on Wikipedia.

bOK = math.resetRandomSeed ( nValue )

Call this Function to set a specified Seed (by the “nValue” parameter – a numeric value) for

the Random Number Generator. This Function returns a value of "True" if the specified Seed

is set successfully, or “False” otherwise. Note that this is useful if you wish to have the same

“randomness” occur every time you make a call to the Random Number Generator.

MICROPHONE

bOK = microphone.addUserToDiffusionList ( hUser )

Call this Function to add a specified User (by the “hUser” parameter) to the Microphone

Diffusion List. This Function returns a value of “True” if the specified User is added to the

Microphone Diffusion List successfully, or “False” otherwise.

bOK = microphone.emptyDiffusionList ( )

Call this Function to remove all Users from the Microphone Diffusion List. This Function

returns a value of "True" if all of the Users are removed from the Microphone Diffusion List


nCount = microphone.getDiffusionListUserCount ( )

Call this Function to obtain the number of Users currently in the Microphone Diffusion List.

This Function returns a numeric value indicating the number of Users currently in the

Microphone Diffusion List.



nUserID = microphone.getDiffusionListUserIDAt ( nIndex )

Call this Function to obtain the User ID of the User in the Microphone Diffusion List at a

specified Index (by the “nIndex” parameter – a zero-based numeric value). This Function

returns a numeric value indicating the User ID of the User in the Microphone Diffusion List.

bYes = microphone.isUserInDiffusionList ( nUserID )

Call this Function to check if a specified User (by the “nUserID” parameter – a numeric value

denoting the User) is currently in the Microphone Diffusion List. This Function returns a

value of “True” if the specified User is in the Microphone Diffusion List, or “False” otherwise.

bOK = microphone.removeUserFromDiffusionList ( nUserID )

Call this Function to remove a specified User (by the “nUserID” parameter – a numeric value

denoting the User) from the Microphone Diffusion List. This Function returns a value of

“True” if the specified User is removed successfully, or “False” otherwise.

bOK = microphone.startDiffusion ( )

Call this Function to start the Microphone Diffusion process. This Function returns a value of

“True” if the Microphone Diffusion process is started successfully, or “False” otherwise.

bOK = microphone.stopDiffusion ( )

Call this Function to stop the Microphone Diffusion process. This Function returns a value of

“True” if the Microphone Diffusion process is stopped successfully, or “False” otherwise.

NAVIGATION

nX, nY, nZ = navigation.getNodeTranslation ( hScene, hNode )

Call this Function to return the x, y, & z co-ordinates of a specified Node (by the “hNode”

parameter) in the 3D GLOBAL space of a specified Scene (by the “hScene” parameter). This

Function returns numeric values corresponding to the X (“nX”), Y (“nY”) & Z (“nZ”) co-

ordinates (in GLOBAL space) of the specified Node.

bYes = navigation.isNodeEnabled ( hScene, hNode )

Call this Function to know if a specified Node (by the “hNode” parameter) of a specified

Scene (by the “hScene” parameter) is enabled, or not. This Function returns a value of

“True” if the specified Node is enabled, or “False” otherwise.



bYes = navigation.isNodeOnBorder ( hScene, hNode )

Call this Function to know if a specified Node (by the “hNode” parameter) of a specified

Scene (by the “hScene” parameter) is on a Navigation Border, or not. This Function returns a

value of “True” if the specified Node is on a Navigation Border, or “False” otherwise.

NETWORK

bOK = network.createServer ( nPort )

Call this Function to create a new Server instance on a specified Port (by the “nPort”

parameter – a numeric value). This Function returns a value of “True” if the new Server is

created successfully, or “False” otherwise.

bOK = network.searchForServers ( nPort )

Call this Function to know if a Server instance is currently running on a specified Port (by the

“nPort” parameter – a numeric value). This Function returns a value of "True" if the Server is

currently running on the specified Port, or “False” otherwise.

network.kDefaultServerPort

This Constant contains a numeric value denoting the default Server Port.

network.kStatusSearchFinished

This Constant contains a boolean value denoting whether the Server search has finished, or

not.



OBJECT

vValue = object.getAIVariable ( hObject, sAIModel, sVariable )

Call this Function to obtain the value of a specified Variable (by the “sVariable” parameter –

a string value), of a specified AIModel (by the “sAIModel” parameter – a string value) of a

specified Object (by the “hObject” parameter). This Function returns the value of the

Variable.

example:

vValue = object.getAIVariable ( hObject, “myAIModel”, “sState” )

bYes = object.hasAIModel ( hObject, sAIModel )

Call this Function to determine if a specified Object (by the “hObject” parameter) has at

least one AIModel. This Function returns a value of “True” if the Object has at least one

AIModel, or “False” otherwise. Note that the 2nd parameter (“sAIModel” – a string value) can

be used to determine if a specified Object has an AIModel denoted by the “sAIModel”

parameter.

example:

if ( object.hasAIModel ( hObject ) )

then

local sAIModelName = object.getAIModelNameAt ( hObject, 0 )

object.removeAIModel ( hObject, sAIModelName )

end

object.kTypeProjector

This Constant holds a boolean value denoting whether the Object is a Projector, or not.



PIXELMAP

bOK = pixelmap.createBrushFromRectangle ( hPixelMap, sBrush, nX1, nY1, nX2, nY2 )

Call this Function to create a specified Brush (by the “sBrush” parameter – a string value) for

a specified PixelMap (by the “hPixelMap” parameter) in the shape of a specified Rectangle

(by the “nX1”, “nY1”, “nX2” & “nY2” parameters – numeric values in Pixels) denoting the two

opposite corners of the Rectangle. This Function returns a value of “True” if the Brush is

created successfully, or “False” otherwise.

bOK = pixelmap.createBrushFromTexture ( hPixelMap, sBrush, sTexture )

Call this Function to create a specified Brush (by the “sBrush” parameter – a string value) for

a specified PixelMap (by the “hPixelMap” parameter) by using a specified Texture (by the

“sTexture” parameter – a string value). This Function returns a value of “True” if the Brush is

created successfully, or “False” otherwise. Note that the Texture to be used must be

preloaded in the Application’s Resources.

example:

if ( pixelmap.createBrushFromTexture ( hPixelMap, “myBrush”, “brush” ) )

then

local bsx = pixelmap.getBrushWidth ( hPixelMap, “myBrush” )

local bsy = pixelmap.getBrushHeight ( hPixelMap, “myBrush” )

pixelmap.setBrushOrigin ( hPixelMap, “myBrush”, bsx / 2 + 1, bsy / 2 + 1 )

end

bOK = pixelmap.destroyBrush ( hPixelMap, sBrush )

Call this Function to delete a specified Brush (by the “sBrush” parameter – a string value) for

a specified PixelMap (by the “hPixelMap” parameter). This Function returns a value of

“True” if the Brush is deleted successfully, or “False” otherwise

bOK = pixelmap.drawLine ( hPixelMap, nX1, nY1, nX2, nY2 )

Call this Function to draw a Line between a specified Points (by the “nX1”, “nY1”, “nX2” &

“nY2” parameters – numeric values in Pixels) in a specified PixelMap (by the “hPixelMap”

parameter. This Function returns a value of “True” if the Line is drawn successfully, or




bOK = pixelmap.drawPoint ( hPixelMap, nX, nY )

Call this Function to draw a point at a specified Point (by the “nX” & “nY” parameters –

numeric values in Pixels) in a specified PixelMap (by the “hPixelMap” parameter. This

Function returns a value of “True” if the Point is drawn successfully, or “False” otherwise.

bOK = pixelmap.drawRectangle ( hPixelMap, nX1, nY1, nX2, nY2 )

Call this Function to fill the Rectangle denoted by a specified points (by the “nX1”, “nY1”,

“nX2” & “nY2” parameters – numeric values in Pixels) in a specified PixelMap (by the

“hPixelMap” parameter). This Function returns a value of “True” if the Rectangle is drawn


nCount = pixelmap.getBrushCount ( hPixelMap )

Call this Function to obtain the number of Brushes attached to a specified PixelMap (by the

“hPixelMap” parameter). This Function returns a numeric value denoting the number of

Brushes.

nHeight = pixelmap.getBrushHeight ( hPixelMap, sBrush )

Call this Function to obtain the Height of a specified Brush (by the “sBrush” parameter – a

string value) for a specified PixelMap (by the “hPixelMap” parameter). This Function returns

a numeric value denoting the Height (in Pixels).

example:


then




end

x, y = pixelmap.getBrushOrigin ( hPixelMap, sBrush )

Call this Function to obtain the current Origin of a specified Brush (by the “sBrush”

parameter – a string value) for a specified PixelMap (by the “hPixelMap” parameter). This

Function returns two numeric values denoting the X & Y co-ordinates (in Pixels).



nWidth = pixelmap.getBrushWidth ( hPixelMap, sBrush )

Call this Function to obtain the Width of a specified Brush (by the “sBrush” parameter – a

string value) for a specified PixelMap (by the “hPixelMap” parameter). This Function returns

a numeric value denoting the Width (in Pixels).

example:


then




end

nHeight = pixelmap.getHeight ( hPixelMap )

Call this Function to obtain the Height of a specified PixelMap (by the “hPixelMap”

parameter). This Function returns a numeric value denoting the Height (in Pixels).

nRed, nGreen, nBlue, nAlpha = pixelmap.getPixel ( hPixelMap, nX, nY )

Call this Function to obtain the colour of a specified Pixel (by the “nX” & “nY” parameters –

numeric values in Pixels) of a specified PixelMap (by the “hPixelMap” parameter). This

Function returns numeric values (between 0 & 255) denoting Red (“nRed”), Green

(“nGreen”), Blue (“nBlue”) & Alpha (“nAlpha”).

hPixelMap = pixelmap.getResourceHandle ( sName )

Call this Function to obtain a Handle to the PixelMap with a specified resource name (by the

“sName” Parameter – a string value). This Function returns the Handle of the PixelMap.

nWidth = pixelmap.getWidth ( hPixelMap )

Call this Function to obtain the Width of a specified PixelMap (by the “hPixelMap”

parameter). This Function returns a numeric value denoting the Width (in Pixels).

bOK = pixelmap.lock ( hPixelMap )

Call this Function to Lock (i.e. prevent further changes to) a specified PixelMap (by the

“hPixelMap” parameter). This Function returns a value of “True” if the PixelMap is locked




bOK = pixelmap.saveToTexture ( hPixelMap, sName )

Call this Function to Save a specified PixelMap (by the “hPixelMap” parameter) as a specified

Texture (by the “sName” parameter – a string value) into the cache. This Function returns a

value of “True” if the PixelMap is saved successfully, or “False” otherwise.

example:

-- Save the PixelMap in a File

pixelmap.saveTexture ( hPixelMap, “myImage.jpg” )

cache.sendToFile ( “myImage.jpg”, “file://”..system.getDocumentsDirectory (

)..”/myImage.jpg” )

bOK = pixelmap.setBlendMode ( hPixelMap, kBlendMode )

Call this Function to set the Blend Mode of a specified PixelMap (by the “hPixelMap”

parameter) using the relevant Constant (by the “kBlendMode” parameter – either

“pixelmap.kBlendModeDecal”, or “kBlendModeReplace”). This Function returns a value of

“True” if the Blend Mode is set successfully, or “False” otherwise.

bOK = pixelmap.setBrushOrigin ( hPixelMap, sBrush, nX, nY )

Call this Function to set a specified Origin (by the “nX” & “nY” parameters – numeric values

in Pixels) of a specified Brush (by the “sBrush” parameter – a string value) of a specified

PixelMap (by the “hPixelMap” parameter). This Function returns a value of “True” if the

Origin is set successfully, or “False” otherwise.

example:

if ( pixelmap.createBrushFromTexture ( hPixelMap, “myBrush, “brush” ) )

then


local bsy = pixelmap.getBrushHeight ( hpixelMap, “myBrush” )


end

bOK = pixelmap.setFillBrush ( hPixelMap, nRed, nGreen, nBlue, nAlpha )

Call this Function to set a specified Fill Brush Colour (by the “nRed”, “nGreen”, “nBlue” &

“nAlpha” parameters – numeric values between 0 & 255) of a specified PixelMap (by the

“hPixelMap” parameter). This Function returns a value of “True” if the Fill Brush Colour is set




bOK = pixelmap.setFillColor ( hPixelMap, nRed, nGreen, nBlue, nAlpha )

Call this Function to set a specified Fill Colour (by the “nRed”, “nGreen”, “nBlue” & “nAlpha”

parameters – numeric values between 0 & 255) of a specified PixelMap (by the “hPixelMap”

parameter). This Function returns a value of “True” if the Fill Colour is set successfully, or


bOK = pixelmap.setFillMode ( hPixelMap, kFillMode )

Call this Function to set a specified Fill Mode (by the “kFillMode” parameter – one of

“pixelmap.kFillModeBrush”, “pixelmap.kFillModeNone” or “pixelmap.kFillModeSolid”) of a

specified PixelMap (by the “hPixelMap” parameter). This Function returns a value of “True”

if the Fill Mode is set successfully, or “False” otherwise.

bOK = pixelmap.setPenBrush ( hPixelMap, sBrush )

Call this Function to set a specified Brush (by the “sBrush” parameter – a string value) of a

specified PixelMap (by the “hPixelMap” parameter). This Function returns a value of “True”

if the Brush is set successfully, or “False” otherwise.

bOK = pixelmap.setPenColor ( hPixelMap, nRed, nGreen, nBlue, nAlpha)

Call this Function to set a specified Pen Colour (by the “nRed”, “nGreen”, “nBlue” &

“nAlpha” parameters – numeric values between 0 & 255) of a specified PixelMap (by the

“hPixelMap” parameter). This Function returns a value of “True” if the Pen Colour is set


bOK = pixelmap.setPenMode ( hPixelMap, kPenMode )

Call this Function to set a specified Pen Mode (by the “kPenMode” parameter – one of

“pixelmap.kPenModeBrush”, “pixelmap.kPenModeNone” or “pixelmap.kPenModeSolid”) of

a specified PixelMap (by the “hPixelMap” parameter). This Function returns a value of

“True” if the Pen Mode is set successfully, or “False” otherwise.

bOK = pixelmap.setPixel ( hPixelMap, nX, nY, nRed, nGreen, nBlue, nAlpha )

Call this Function to set a specified Colour (by the “nRed”, “nGreen”, “nBlue” & “nAlpha”

parameters – numeric values between 0 & 255) of a specified Pixel ( by the “nX” & “nY”

parameters – numeric values in Pixels) of a specified PixelMap (by the “hPixelMap”

parameter). This Function returns a value of “True” if the Colour is set successfully, or




bOK = pixelmap.unlock ( hPixelMap )

Call this Function to Unlock (i.e. allow further changes to) a specified PixelMap (by the

“hPixelMap” parameter). This Function returns a value of “True” if the PixelMap is unlocked


pixelmap.kBlendModeDecal

This Constant holds a boolean value denoting whether Decal Blend is being used for

PixelMap blending, or not.

pixelmap.kBlendModeReplace

This Constant holds a boolean value denoting whether Replace Blend is being used for

PixelMap blending, or not.

pixelmap.kFillModeBrush

This Constant holds a boolean value denoting whether a Brush is being used in Fill mode, or

not.

pixelmap.kFillModeNone

This Constant holds a boolean value denoting whether nothing is being used in Fill mode, or

not.

pixelmap.kFillModeSolid

This Constant holds a boolean value denoting whether a Solid Colour is being used in Fill

mode, or not.

pixelmap.kPenModeBrush

This Constant holds a boolean value denoting whether a Brush is being used in Pen mode, or

not.

pixelmap.kPenModeNone

This Constant holds a boolean value denoting whether nothing is being used in Pen mode, or

not.



pixelmap.kPenModeSolid

This Constant holds a boolean value denoting whether a Solid Colour is being used in Pen

mode, or not.

PROJECTOR

bOK = projector.setColor ( hObject, “nRed”, “nGreen”, “nBlue” )

Call this Function to set a specified Colour (by the “nRed”, “nGreen” & “nBlue” – as numeric

values between 0 & 1) of the Projector attached to a specified Object (by the “hObject”

parameter). This Function returns a value of “True” if the Colour is set successfully, or


nRed, nGreen, nBlue = projector.getColor ( hObject )

Call this Function to obtain the current Colour of the Projector attached to a specified Object

(by the “hObject” parameter). This Function returns numeric values (between 0 & 1)

denoting Red (“nRed”), Green (“nGreen”) & Blue (“nBlue”).

bOK = projector.setOpacity ( hObject, nOpacity )

Call this Function to set a specified Opacity (by the “nOpacity” parameter – a numeric value

between 0 & 1) of the Projector attached to a specified Object (by the “hObject” parameter).

This Function returns a value of “True” if the Opacity is set successfully, or “False” otherwise.

nOpacity = projector.getOpacity ( hObject )

Call this Function to obtain the current Opacity of the Projector attached to a specified

Object (by the “hObject” parameter). This Function returns a numeric value (between 0 & 1).

bOK = projector.setMinClipDistance ( hObject, nDistance )

Call this Function to set a specified Minimum Clip Distance (by the “nDistance” parameter –

a numeric value between 0 & 99.9) of the Projector attached to a specified Object (by the

“hObject” parameter). This Function returns a value of “True” if the Minimum Clip Distance

is set successfully, or “False” otherwise.

nDistance = projector.getMinClipDistance ( hObject )

Call this Function to obtain the current Minimum Clip Distance of the Projector attached to a

specified Object (by the “hObject” parameter). This Function returns a numeric value

(between 0 & 99.9).



bOK = projector.setMaxClipDistance ( hObject, nDistance )

Call this Function to set a specified Maximum Clip Distance (by the “nDistance” parameter –

a numeric value between 0.1 & 100) of the Projector attached to a specified Object (by the

“hObject” parameter). This Function returns a value of “True” if the Maximum Clip Distance

is set successfully, or “False” otherwise.

nDistance = projector.getMaxClipDistance ( hObject )

Call this Function to obtain the current Maximum Clip Distance of the Projector attached to

a specified Object (by the “hObject” parameter). This Function returns a numeric value

(between 0.1 & 100).

bOK = projector.setFieldOfView ( hObject, nAngle )

Call this Function to set a specified Field of View angle (by the “nAngle” parameter – a

numeric value between 1 & 89) of the Projector attached to a specified Object (by the

“hObject” parameter). This Function returns a value of “True” if the Field of View angle is set


nAngle = projector.getFieldOfView ( hObject )

Call this Function to obtain the current Field of View angle of the Projector attached to a

specified Object (by the “hObject” parameter). This Function returns a numeric value

(between 1 & 89).

bOK = projector.setMap ( hObject, kMapType, sMapName)

Call this Function to set a specified Map (by the “sMapName” parameter – a string value

denoting the name of the Map) using a specified Map Type (by the “kMapType” parameter –

one of “kMapTypeTexture”, “kMapTypeTextureClip”, “kMapTypeRenderMap”,

“kMapTypePixelMap” or “kMapTypeMovie”) on a specified Object (by the “hObject”

parameter). This Function returns “True” if the Map is set successfully, or “False” otherwise.

bOK = projector.playMapMovie ( hObject )

Call this Function to play a Movie on a specified Object (by the “hObject” parameter). This

Function returns “True” if the Movie is played successfully, or “False” otherwise.

bOK = projector.pauseMapMovie ( hObject )

Call this Function to pause a Movie currently playing on a specified Object (by the “hObject”

parameter). This Function returns “True” if the Movie is paused successfully, or “False”

otherwise.



bOK = projector.stopMapMovie ( hObject )

Call this Function to stop a Movie currently playing on a specified Object (by the “hObject”

parameter). This Function returns “True” if the Movie is stopped successfully, or “False”

otherwise.

projector.kMapTypeTexture

This Constant denotes a Texture Projector Map.

projector.kMapTypeTextureClip

This Constant denotes a Texture Clip Projector Map.

projector.kMapTypeRenderMap

This Constant denotes a RenderMap Projector Map.

projector.kMapTypePixelMap

This Constant denotes a PixelMap Projector Map.

projector.kMapTypeMovie

This Constant denotes a Movie Projector Map.

SCENE

bOK = scene.createOcean ( hScene, nGridSize, nUnitSize, nWavesTiling )

Call this Function to create an Ocean in a specified Scene (by the “hScene” parameter). The

options available are Grid Size (by the “nGridSize” parameter – a numeric value, one of 8, 16,

32, 64, 128 & 256), Unit Size (by the “nUnitSize” parameter – a numeric value between 0.1 &

2) and the Tiling of the Waves (by the “nTiling” parameter – a numeric value, one of 1, 2, 4,

8, & 16). This Function returns a value of “True” if the Ocean is created successfully, or


bOK = scene.destroyOcean ( hScene )

Call this Function to destroy the Ocean attached to a specified Scene (by the “hScene”

parameter). This Function returns a value of “True” if the Ocean is destroyed successfully, or




nFactor = scene.getBloomMotionBlurFactor ( hScene )

Call this Function to obtain the current Bloom Motion Blur Factor of a specified Scene (by

the “hScene” parameter). This Function returns a numeric value (between 0 & 1).

nDistance = scene.getDynamicShadowsFadeDistance ( hScene )

Call this Function to obtain the current Fade Distance of the Dynamic Shadows of a specified

Scene (by the “hScene” parameter). This Function returns a numeric value (between 0 &

1000).

nDistance = scene.getDynamicShadowsMaxDistance ( hScene )

Call this Function to obtain the current maximum Distance of the Dynamic Shadows of a

specified Scene (by the “hScene” parameter). This Function returns a numeric value

(between 0 & 1000).

nIterations = scene.getDynamicsIterationsPerStep ( hScene )

Call this Function to obtain the current Iterations per step of the Physics of a specified Scene

(by the “hScene” parameter). This Function returns a numeric value.

hHitObject, nHitDist, nX, nY, nZ, nI, nJ, nK = scene.getFirstHitColliderWithIDEx (

hScene, nRayPosX, nRayPosY, nRayPosZ, nRayDirX, nRayDirY, nRayDirZ, nRayLength,

nSurfaceID )

Call this Function to obtain the first Hit Collider of a specified Scene (by the “hScene”

parameter), with a specified Surface ID (by the “nSurfaceID” parameter – a zero-based

numeric value), when a Ray is fired from a specified point (by the “nRayPosX”, “nRayPosY” &

“nRayPosZ” parameters – numeric values in Pixels) in a specified direction (by the

“nRayDirX”, “nRayDirY” & “nRayDirZ” parameters – numeric values between 0 & ∞). This

Function returns a Handle to the Hit Object (“nHitObject”), a numeric value denoting the

distance to the Hit Object (“nHitDist”), numeric values (in Pixels) denoting the position of the

Hit Object (“nX”, “nY” & “nZ”), and numeric values (between 0 & ∞) denoting the direction

of the Hit Object (“nI”, “nJ” & “nK”).

NOTE: the value for “nRayLength” should be kept as small as possible to avoid precision

errors.



hHitObject, nHitDist, nHitSensorID = scene.getFirstHitSensorWithIDInRange( hScene,

nRayPosX, nRayPosY, nRayPosZ, nRayDirX, nRayDirY, nRayDirZ, nRayLength,

nMinSensorID, nMaxSensorID )

Call this Function to obtain the first Hit Sensor of a specified Scene (by the “hScene”

parameter), with a specified Sensor ID between a minimum value (by the “nMinSensorID”

parameter – a zero-based numeric value) and a maximum value (by the “nMaxSensorID”

parameter – a zero-based numeric value), when a Ray is fired from a specified point (by the

“nRayPosX”, “nRayPosY” & “nRayPosZ” parameters – numeric values in Pixels) in a specified

direction (by the “nRayDirX”, “nRayDirY” & “nRayDirZ” parameters – numeric values

between 0 & ∞),. This Function returns a Handle to the Hit Object (“nHitObject”), a numeric

value denoting the distance to the Hit Object (“nHitDist”), and the ID of the Hit Sensor

(“nHitSensorID”).

NOTE: the value for “nRayLength” should be kept as small as possible to avoid precision

errors.

nSize = scene.getNormalMappingFadeScreenSize ( hScene )

Call this Function to obtain the current Fade Distance of the Normal Mapping of a specified


100).

nSize = scene.getNormalMappingMinScreenSize ( hScene )

Call this Function to obtain the current minimum Screen size of the Normal Mapping of a


(between 0 & 100).

nTiling = scene.getOceanFoamMapTiling ( hScene )

Call this Function to obtain the current Tiling of the Ocean of a specified Scene (by the

“hScene” parameter). This Function returns a numeric value (between 0.1 & 4).

nBias = scene.getOceanFresnelBias ( hScene )

Call this Function to obtain the current Fresnel Bias of the Ocean of a specified Scene (by the

“hScene” parameter). This Function returns a numeric value (between 0 & 1).

nPower = scene.getOceanFresnelPower ( hScene )

Call this Function to obtain the current Fresnel Power of the Ocean of a specified Scene (by

the “hScene” parameter). This Function returns a numeric value (between 2 & 16).



nHeight = scene.getOceanHeight ( hScene , nX, nZ )

Call this Function to obtain the current Height of the Ocean of a specified Scene (by the

“hScene” parameter) at a specified point (by the “nX” & “nZ” parameters – numeric values

denoting the location in Pixels). This Function returns a numeric value dependant on the

Ocean Mean Height & Amplitude).

nI, nJ, nK = scene.getOceanNormal ( hScene, nX, nZ )

Call this Function to obtain the current Normal of the Ocean of a specified Scene (by the

“hScene” parameter) at a specified point (by the “nX” & “nZ” parameters – numeric values

denoting the location in Pixels). This Function returns numeric values (between -1 & 1)

denoting the direction of the Normal in I (“nI”), J (“nJ”) & K (“nK”).

nTiling = scene.getOceanNormalMapTiling ( hScene )

Call this Function to obtain the current Tiling of the Normal Map of the Ocean of a specified

Scene (by the “hScene” parameter). This Function returns a numeric value (between 0 & ∞).

nScale = scene.getOceanReflectionNoiseScale ( hScene )

Call this Function to obtain the current scale of the Reflection Noise of the Ocean of a


(between 0 & 1)

nBias = scene.getOceanReflectorBias ( hScene )

Call this Function to obtain the current bias of the Reflector of the Ocean of a specified

Scene (by the “hScene” parameter). This Function returns a numeric value (between -1 & 1)

nScale = scene.getOceanRefractionNoiseScale ( hScene )

Call this Function to obtain the current scale of the Refraction Noise of the Ocean of a


(between 0 & 1)

nRed, nGreen, nBlue = scene.getOceanSurfaceColor ( hScene )

Call this Function to obtain the current Surface Colour of the Ocean of a specified Scene (by

the “hScene” parameter). This Function returns numeric values (between 0 & 1) denoting

Red (“nRed”), Green (“nGreen”) & Blue (“nBlue”).



nFactor = scene.getOceanSurfaceColorFactor ( hScene )

Call this Function to obtain the current Surface Colour Factor of the Ocean of a specified

Scene (by the “hScene” parameter). This Function returns a numeric value (between 0 & 1).

nDistance = scene.getOceanSurfaceColorMaxDistance ( hScene )

Call this Function to obtain the current maximum Surface Colour Distance of the Ocean of a


(between 0 & 1000).

nRed, nGreen, nBlue = scene.getOceanUnderwaterFogColor ( hScene )

Call this Function to obtain the current Underwater Fog Colour of the Ocean of a specified

Scene (by the “hScene” parameter). This Function returns numeric values (between 0 & 1)

denoting Red (“nRed”), Green (“nGreen”) & Blue (“nBlue”).

nDensity = scene.getOceanUnderwaterFogDensity ( hScene )

Call this Function to obtain the current Underwater Fog Density of the Ocean of a specified

Scene (by the “hScene” parameter). This Function returns a numeric value (between 0 & 1).

nAmplitude = scene.getOceanWavesAmplitude ( hScene )

Call this Function to obtain the current Wave Amplitude of the Ocean of a specified Scene

(by the “hScene” parameter). This Function returns a numeric value (between 0 & 8).

nFrequency = scene.getOceanWavesFrequency ( hScene )

Call this Function to obtain the current Wave Frequency of the Ocean of a specified Scene

(by the “hScene” parameter). This Function returns a numeric value (between 0 & 1).

nHeight = scene.getOceanWavesMeanHeight ( hScene )

Call this Function to obtain the current mean Wave Height of the Ocean of a specified Scene

(by the “hScene” parameter). This Function returns a numeric value (between -10 & 10).

nSize = scene.getPerPixelLightingMinScreenSize ( hScene )

Call this Function to obtain the current minimum Screen size for the PerPixel Lighting of a


(between 0 & 100).



nSize = scene.getSpecularLightingFadeScreenSize ( hScene )

Call this Function to obtain the current Screen size for the Fade of the Specular Lighting of a


(between 0 & 100).

nSize = scene.getSpecularLightingMinScreenSize ( hScene )

Call this Function to obtain the minimum Screen size for the Specular Lighting of a specified


100).

nCount = scene.getTerrainVegetationLayerCount ( hScene )

Call this Function to obtain the count of the number of layers of the Vegetation of the

Terrain the specified Scene (by the “hScene” parameter). This Function returns a numeric

value (between 0 & ∞).

bOK = scene.setBackgroundTextureFilteringMode ( hScene, kFilteringMode )

Call this Function to set a specified Background Texture Filtering (by the “kFilteringMode”

parameter – one of “kFilteringModeBilinear”, “kFilteringModeNearest” or

“kFilteringModeTrilinear”) of a specified Scene (by the “hScene” parameter). This Function

returns a value of “True” if the Filtering Mode is set successfully, or “False” otherwise.

bOK = scene.setBloomMotionBlurFactor ( hScene, nFactor )

Call this Function to set a specified Bloom Motion Blur Factor (by the “nFactor” parameter –

a numeric value between 0 & 1) of a specified Scene (by the “hScene” parameter). This

Function returns a value of “True” if the Factor is set successfully, or “False” otherwise.

bOK = scene.setDynamicShadowsFadeDistance ( hScene, nDistance )

Call this Function to set a specified Dynamic Shadows Fade Distance (by the “nDistance”

parameter – a numeric value between 0 & 1000) of a specified Scene (by the “hScene”

parameter). This Function returns a value of “True” if the Distance is set successfully, or


bOK = scene.setDynamicShadowsMaxDistance ( hScene, nDistance )

Call this Function to set a specified maximum Distance for Dynamic Shadows (by the

“nDistance” parameter – a numeric value between 0 & 1000) of a specified Scene (by the

“hScene” parameter). This Function returns a value of “True” if the Distance is set




bOK = scene.setDynamicsIterationsPerStep ( hScene, nIterations )

Call this Function to set a number of Iterations per Step for Physics (by the “nIterations”

parameter – a numeric value between 1 & 360, with a default of 120) of a specified Scene

(by the “hScene” parameter). This Function returns a value of “True” if the number of

Iterations is set successfully, or “False” otherwise.

bOK = scene.setNormalMappingFadeScreenSize ( hScene, nSize )

Call this Function to set a specified Fade Screen size for Normal Mapping (by the “nSize”


parameter). This Function returns a value of “True” if the size is set successfully, or “False”

otherwise.

bOK = scene.setNormalMappingMinScreenSize ( hScene, nSize )

Call this Function to set a specified minimum Screen size for Normal Mapping (by the “nSize”


parameter). This Function returns a value of “True” if the size is set successfully, or “False”

otherwise.

bOK = scene.setOceanFoamMap ( hScene, sMapName )

Call this Function to set a specified Foam Map (by the “sMapName” parameter – a string

denoting the name of the Map to be applied) of the Ocean of a specified Scene (by the

“hScene” parameter). This Function returns a value of “True” if the Map is set successfully,

or “False” otherwise.

bOK = scene.setOceanFoamMapTiling ( hScene, nTiling )

Call this Function to set a specified Foam Map Tiling (by the “nTiling” parameter – a numeric

value between 0.1 & 4) of the Ocean of a specified Scene (by the “hScene” parameter). This

Function returns a value of “True” if the Tiling is set successfully, or “False” otherwise.

bOK = scene.setOceanFresnelBias ( hScene, nBias )

Call this Function to set a specified Fresnel Bias (by the “nBias” parameter – a numeric value

between 0 & 1) of the Ocean of a specified Scene (by the “hScene” parameter). This

Function returns a value of “True” if the Bias is set successfully, or “False” otherwise.



bOK = scene.setOceanFresnelPower ( hScene, nPower )

Call this Function to set a specified Fresnel Power (by the “nPower” parameter – a numeric

value between 2 & 16) of the Ocean of a specified Scene (by the “hScene” parameter). This

Function returns a value of “True” if the Power is set successfully, or “False” otherwise.

bOK = scene.setOceanNormalMapTiling ( hScene, nTiling )

Call this Function to set a specified Tiling (by the “nTiling” parameter – a numeric value

between 0 & ∞, usually between 0.01 & 16) of the Normal Map of the Ocean of a specified

Scene (by the “hScene” parameter). This Function returns a value of “True” if the Tiling is set


bOK = scene.setOceanReflectionNoiseScale ( hScene, nScale )

Call this Function to set a specified Reflection Noise Scale (by the “nScale” parameter – a

numeric value between 0 & 1) of the Ocean of a specified Scene (by the “hScene”

parameter). This Function returns a value of “True” if the Scale is set successfully, or “False”

otherwise.

bOK = scene.setOceanReflectorBias ( hScene, nBias )

Call this Function to set a specified Reflector Bias (by the “nBias” parameter – a numeric

value between -1 & 1) of the Ocean of a specified Scene (by the “hScene” parameter). This

Function returns a value of “True” if the Bias is set successfully, or “False” otherwise.

bOK = scene.setOceanRefractionNoiseScale ( hScene, nScale )

Call this Function to set a specified Refraction Noise Scale (by the “nScale” parameter – a


parameter). This Function returns a value of “True” if the Scale is set successfully, or “False”

otherwise.

bOK = scene.setOceanSurfaceColor ( hScene, nRed, nGreen, nBlue )

Call this Function to set a specified Surface Colour (by the “nRed”, “nGreen” & “nBlue”

parameters – numeric values between 0 & 1) of the Ocean of a specified Scene (by the

“hScene” parameter). This Function returns a value of “True” if the Colour is set successfully,




bOK = scene.setOceanSurfaceColorFactor ( hScene, nFactor )

Call this Function to set a specified Surface Colour Factor (by the “nFactor” parameter – a


parameter). This Function returns a value of “True” if the Factor is set successfully, or “False”

otherwise.

bOK = scene.setOceanSurfaceColorMaxDistance ( hScene, nDistance )

Call this Function to set a specified maximum Surface Colour Distance (by the “nDistance”

parameter – a numeric value between 0 & 1000) of the Ocean of a specified Scene (by the

“hScene” parameter). This Function returns a value of “True” if the Distance is set


bOK = scene.setOceanUnderwaterFogColor ( hScene, nRed, nGreen, nBlue )

Call this Function to set a specified Underwater Fog Colour (by the “nRed”, “nGreen” &

“nBlue” parameters – numeric values between 0 & 1) of the Ocean of a specified Scene (by

the “hScene” parameter). This Function returns a value of “True” if the Colour is set


bOK = scene.setOceanUnderwaterFogDensity ( hScene, nDensity )

Call this Function to set a specified Underwater Fog Density (by the “nDensity” parameter –

a numeric value between 0 & 1) of the Ocean of a specified Scene (by the “hScene”

parameter). This Function returns a value of “True” if the Density is set successfully, or


bOK = scene.setOceanWavesAmplitude ( hScene, nAmplitude )

Call this Function to set a specified Wave Amplitude (by the “nAmplitude” parameter – a


parameter). This Function returns a value of “True” if the Amplitude is set successfully, or


bOK = scene.setOceanWavesFrequency ( hScene, nFrequency )

Call this Function to set a specified Wave Frequency (by the “nFrequency” parameter – a


parameter). This Function returns a value of “True” if the Frequency is set successfully, or




bOK = scene.setOceanWavesMeanHeight ( hScene, nHeight )

Call this Function to set a specified Mean Wave Height (by the “nHeight” parameter – a

numeric value between -10 & 10) of the Ocean of a specified Scene (by the “hScene”

parameter). This Function returns a value of “True” if the Height is set successfully, or


bOK = scene.setPerPixelLightingMinScreenSize ( hScene, nSize )

Call this Function to set a specified minimum Screen Size (by the “nSize” parameter – a

numeric value between 0 & 100) for PerPixel Lighting of a specified Scene (by the “hScene”

parameter). This Function returns a value of “True” if the Size is set successfully, or “False”

otherwise.

bOK = scene.setSkyBoxFaceMap ( hScene, kFace, sMapName )

Call this Function to set a specified Map (by the “nMapName” parameter – a string value) for

a specified Face (by the “kFace” parameter – one of the relevant SkyBox Face Constants) of

the SkyBox of a specified Scene (by the “hScene” parameter). This Function returns a value

of “True” if the Map is set successfully, or “False” otherwise.

bOK = scene.setSpecularLightingFadeScreenSize ( hScene, nSize )

Call this Function to set a specified Fade Distance (by the “nDistance” parameter – a numeric

value between 0 & 100) for Specular Lighting of a specified Scene (by the “hScene”

parameter). This Function returns a value of “True” if the Distance is set successfully, or


bOK = scene.setSpecularLightingMinScreenSize ( hScene, nSize )

Call this Function to set a specified minimum Screen Size (by the “nSize” parameter – a

numeric value between 0 & 100) for Specular Lighting of a specified Scene (by the “hScene”

parameter). This Function returns a value of “True” if the Size is set successfully, or “False”

otherwise.

bOK = scene.setTerrainTextureFilteringMode ( hScene, kFilteringMode )

Call this Function to set a specified Texture Filtering Mode (by the “kFilteringMode”


“kFilteringModeTrilinear”) for the Terrain of a specified Scene (by the “hScene” parameter).

This Function returns a value of “True” if the Filtering Mode is set successfully, or “False”

otherwise.



bOK = scene.setTerrainVegetationLayerTextureFilteringMode ( hScene, nLayer,

kFilteringMode )

Call this Function to set a specified Texture Filtering Mode (by the “kFilteringMode”


“kFilteringModeTrilinear”) for a specified Layer (by the “nLayer” parameter – a zero-based

numeric value) of the Terrain of a specified Scene (by the “hScene” parameter). This

Function returns a value of “True” if the Filtering Mode is set successfully, or “False”

otherwise.

bOK = scene.setColorContrast ( hScene, nContrast )

Call this Function to set a specified Colour Contrast (by the “nContrast” parameter – a

numeric value between -1 & 1) for a specified Scene (by the “hScene” parameter). This

Function returns a value of “True” if the Contrast is set successfully, or “False” otherwise.

nContrast = scene.getColorContrast ( hScene )

Call this Function to obtain the current Colour Contrast of a specified Scene (by the “hScene”

parameter). This Function returns a numeric value (between -1 & 1).

scene.kFilteringModeBilinear

This Constant denotes the Bilinear Filtering Mode.

scene.kFilteringModeNearest

This Constant denotes the Nearest Filtering Mode.

scene.kFilteringModeTrilinear

This Constant denotes the Trilinear Filtering Mode.

scene.kSkyBoxFaceBack

This Constant denotes the Back Face of the SkyBox.

scene.kSkyBoxFaceBottom

This Constant denotes the Bottom Face of the SkyBox.

scene.kSkyBoxFaceFront

This Constant denotes the Front Face of the SkyBox.



scene.kSkyBoxFaceLeft

This Constant denotes the Left Face of the SkyBox.

scene.kSkyBoxFaceRight

This Constant denotes the Right Face of the SkyBox.

scene.kSkyBoxFaceTop

This Constant denotes the Top Face of the SkyBox.

SENSOR

bOK = sensor.add ( hObject, kShapeType )

Call this Function to add a specified Shape Sensor (by the “kShapeType” parameter – one of

“sensor.kBoxType” or “sensor.kSphereType”) to a specified Object (by the “hObject”

parameter). This Function returns a value of “True” if the Sensor is added successfully, or


kShapeType = sensor.getShapeTypeAt ( hObject, nIndex )

Call this Function to determine the Shape Type of a specified Sensor (by the “nIndex”

parameter –a zero-based numeric value of all Sensors attached to the Object) attached to a

specified Object (by the “hObject” parameter). This Function returns a value of

“sensor.kShapeTypeBox”, “sensor.kShapeTypeSphere” or “nil” if no Sensor is attached.

bActive = sensor.isActiveAt ( hObject, nIndex )

Call this Function to determine if a specified Sensor (by the “nIndex” parameter –a zero-

based numeric value of all Sensors attached to the Object) attached to a specified Object (by

the “hObject” parameter) is currently Active. This Function returns a value of “True” if the

Sensor is currently Active, or “False” otherwise.

bOK = sensor.removeAll ( hObject )

Call this Function to remove all Sensors attached to a specified Object (by the “hObject”

parameter). This Function returns a value of “True” if all Sensors are removed successfully,




bOK = sensor.removeAt ( hObject, nIndex )

Call this Function to remove a specified Sensor (by the “nIndex” parameter –a zero-based

numeric value of all Sensors attached to the Object) attached to a specified Object (by the

“hObject” parameter). This Function returns a value of “True” if the Sensor is removed


sensor.kShapeTypeBox

This Constant holds a boolean value denoting whether a Box is being used for the Sensor, or

not.

sensor.kShapeTypeSphere

This Constant holds a boolean value denoting whether a Sphere is being used for the Sensor,

or not.

SERVER

bOK = server.sendEvent ( hServer, sAIModel, sEvent, ... )

Call this Function to send Events to a specified Server (by the “hServer” parameter). The

Event(s) are denoted by a specified AIModel (by the “sAIModel” parameter – a string value

denoting the name of the AIModel) and a specified Event (by the “sEvent” parameter – a

string value denoting the name of the Event of a specified AIModel). This Function returns a

value of “True” if the Event is sent to the Server successfully, or “False” otherwise.



SFX

bOK = sfx.setParticleEmitterLifeTimeFactorAt ( hObject, nIndex, nFactor )

Call this Function to set a specified Life Time Factor (by the “nFactor” parameter – a numeric

value between 0 & ∞) of a specified Particle Emitter (by the “nIndex” parameter – a zero-

based numeric value of all Particle Emitters attached to the Object) attached to a specified

Object (by the “hObject” parameter). This Function returns a value of “True” if the Factor is

set successfully, or “False” otherwise.

bOK = sfx.setParticleEmitterUniformScaleAt ( hObject, nIndex, nFactor )

Call this Function to set a specified Uniform Scale of the Particles (by the “nFactor”

parameter – a numeric value between 0 & ∞) of a specified Particle Emitter (by the “nIndex”

parameter – a zero-based numeric value of all Particle Emitters attached to the Object)

attached to a specified Object (by the “hObject” parameter). This Function returns a value of

“True” if the Scale is set successfully, or “False” otherwise.

SHAPE

nProgress = shape.getMeshSubsetMaterialEffectMap0MovieBufferingProgress (

hObject, nSubsetIndex )

Call this Function to obtain the current Buffering progress of a specified Effect Map Movie

(by the “nSubsetIndex” parameter – a zero-based numeric value) of a specified Object (by

the “hObject” parameter). This Function returns a numeric value (between 0 & 1).

sName = shape.getSkeletonJointNameAt ( hObject, iJointIndex )

Call this Function to obtain the name of a specified Skeleton Joint (by the “iJointIndex”

parameter – a zero-based numeric value) of a specified Object (by the “hObject” parameter).

This Function returns a string.

sParent = shape.getSkeletonJointParentJointName ( hObject, sJointName )

Call this Function to obtain the name of Parent Joint of a specified Skeleton Joint (by the

“sJointName” parameter – a string value) of a specified Object (by the “hObject”

parameter). This Function returns a string.



bOK = shape.overrideMeshMaterialSpecular ( hObject, nRed, nGreen, nBlue, nFactor )

Call this Function to override the Specular Material Mesh of a specified Object (by the

“hObject” parameter) using a Colour (by the “nRed”, “nGreen” & “nBlue” parameters –

numeric values between 0 & 1), and a Factor (by the “nFactor” parameter – a numeric value

between 0 & 1). This Function returns “True” if the Specular is overridden successfully, or


bOK = shape.overrideMeshSubsetMaterialSpecular ( hObject, nSubsetIndex, nRed,

nGreen, nBlue, nFactor )

Call this Function to override the Specular Material Mesh of a specified Subset (by the

“nSubsetIndex” parameter – a zero-based numeric value) of a specified Object (by the

“hObject” parameter) using a Colour (by the “nRed”, “nGreen” & “nBlue” parameters –

numeric values between 0 & 1), and a Factor (by the “nFactor” parameter – a numeric value

between 0 & 1). This Function returns “True” if the Specular is overridden successfully, or


bOK = shape.setMeshSubsetMaterialEffectMap0MovieTransparentColor ( hObject,

nSubsetIndex, nRed, nGreen, nBlue, nTolerance )

Call this Function to set the Movie Transparency Colour (by the “nRed”, “nGreen” & “nBlue”

parameters – numeric values between 0 & 1) of a specified Subset Material (by the

“nSubsetIndex” parameter – a zero-based numeric value) of a specified Object (by the

“hObject” parameter) using a Tolerance factor (by the “nTolerance” parameter – a numeric

value between 0 & 1). This Function returns “True” if the Transparency Colour is set


shape.kMapTypePixelMap

This Constant holds a boolean value denoting whether a PixelMap is being used as the Map

of the Shape, or not.



SOUND

bOK = sound.resume ( hObject, nSoundIndex )

Call this Function to resume a specified Sound (by the “nSoundIndex” parameter) of a

specified Object (by the “hObject” parameter). This Function returns a value of “True” if the

Sound is successfully resumed, or “False” otherwise.

bOK = sound.setPlaybackProgress ( hObject, nSoundIndex, nValue )

Call this Function to set the progress of the Playback of a specified Sound (by the

“nSoundIndex” parameter – a zero-based numeric value) of a specified Object (by the

“hObject” parameter). The progress of the Playback is set using the “nValue” parameter, (a

numeric value between 0 & 1, with 0 meaning the start of the Sound, and 1 meaning the

end). This Function returns a value of “True” if the progress of the Playback is successfully

set, or “False” otherwise.

bOK = sound.setSpatializationReferenceDistance ( hObject, nFactor )

Call this Function to set the 3D Spatialisation Rolloff Factor of all Sounds of a specified Object

(by the “hObject” parameter). The 3D Spatialisation Rolloff Factor is set using the “nFactor”

parameter (a numeric value between 0 & ∞, with a default value of 1). This Function returns

a value of “True” if the Factor is successfully set, or “False” otherwise.

STRING

sString = string.decodeHTML ( sString )

Call this Function to decode a specified HTML String (by the “sString” parameter) into a Text

String, with the HTML Characters converted to proper Text Characters. This Function returns

a string.

sString = string.decodeURL ( sString )

Call this Function to decode a specified URL String (by the “sString” parameter) into a Text

String, with the URL Characters converted to proper Text Characters. This Function returns a

string.

sString = string.encodeHTML ( sString )

Call this Function to encode a specified Text String (by the “sString” parameter) into a HTML

String, with the Text Characters converted to proper HTML Characters. This Function returns

a string.



sString = string.encodeURL ( sString )

Call this Function to encode a specified Text String (by the “sString” parameter) into a URL

String, with the Text Characters converted to proper URL Characters. This Function returns a

string.

bOK = string.explode ( sString, tResult, sDelimiter )

Call this Function to split a specified String (by the “sString” parameter) into a specified Table

(by the “tResult” parameter) using a specified Delimiter (by the “sDelimiter” parameter).

This Function returns a value of “True” if the String is successfully split, or “False” otherwise.

SYSTEM

bYes = system.areHeadingUpdatesEnabled ( )

Call this Function to know if updates to the Heading (used for the new Compass

functionality) are enabled in the System. This Function returns “True” if updates are

enabled, or “False” otherwise.

bYes = system.areHeadingUpdatesSupported ( )

Call this Function to know if updates to the Heading (used by the new Compass functionality)

are supported in the System. This Function returns “True” if updates are supported, or


bOK = system.enableHeadingUpdates ( )

Call this Function to enable updates to the Heading (used by the new Compass

functionality). This Function returns “True” if updates are enabled successfully, or “False”

otherwise.

kType = system.getClientType ( )

Call this Function to obtain the Client Type of the System. This Function returns one of the

Client Type Constants (“kClientTypeEditor”, “kClientTypeEmbedded” or

“kClientTypeStandalone”).

sPath = system.getDocumentsDirectory ( )

Call this Function to obtain the absolute path of the System Document Directory. This

Function returns a String.



nHeading = system.getLastKnownHeading ( )

Call this Function to obtain the last known Heading (used for the new Compass

functionality). This Function returns a numeric value (between 0 & 360).

NOTE: Returns a value of -1 if not initialised, or unavailable.

nHeading = system.getLastKnownTrueHeading ( )

Call this Function to obtain the last known True Heading (used for the new Compass

functionality). This Function returns a numeric value (between 0 & 360).

NOTE: Returns a value of -1 if not initialised, or unavailable.

sPath = system.getPicturesDirectory ( )

Call this Function to obtain the absolute path of the System Picture Directory. This Function

returns a String.

nWidth, nHeight = system.getSupportedScreenResolutionAt ( nIndex )

Call this Function to obtain the Screen Resolution at a specified Index (by the “nIndex”

parameter – a zero-based numeric value). This Function returns numeric values containing

the Width (“nWidth” in Pixels) and the Height (“nHeight” in Pixels).

nCount = system.getSupportedScreenResolutionCount ( )

Call this Function to obtain the number of supported Screen Resolutions of the System. This

Function returns a numeric value containing the number of supported Screen Resolutions.

nWidth, nHeight = system.getCurrentScreenResolution ( )

Call this Function to obtain the currently selected Screen Resolution of the System. This

Function returns numeric values containing the Width (“nWidth” in Pixels) and the Height

(“nHeight” in Pixels).

sModelDescription = system.getGPUModelDescription ( )

Call this Function to obtain the name of the GPU in the current System. This Function returns

a String.

sDriverDescription = system.getGPUDriverDescription ( )

Call this Function to obtain the description of the Driver used by the GPU in the current

System. This Function returns a String containing the description of the Driver used by the

GPU in the current System.



system.kClientTypeEditor

This Constant holds a boolean value denoting whether an Editor Client is being used, or not.

system.kClientTypeEmbedded

This Constant holds a boolean value denoting whether an Embedded Client is being used, or

not.

system.kClientTypeStandalone

This Constant holds a boolean value denoting whether a Standalone Client is being used, or

not.

system.kGPUCapabilityDepthBlurFilterSupport

This Constant holds a boolean value denoting whether the GPU has Depth Blur Filter

capabilities, or not.

Depth Blur (according to Wikipedia) recreates an effect caused by the optics of a lens.

Images formed through a lens are in correct focus only when the subject is directly at a

certain distance (the focal plane). Objects nearer or farther blur. This is often recreated by

blurring the frame buffer to a temporary texture, and drawing over the frame buffer with

that blurred version, alpha blending is used based on the depth of the scene.

system.kGPUCapabilityDistortionFilterSupport

This Constant holds a boolean value denoting whether the GPU has Distortion Filter


A Distortion Filter is used to create an effect whereby the image is distorted when rendered.

system.kGPUCapabilityMotionBlurFilterSupport

This Constant holds a boolean value denoting whether the GPU has Motion Blur Filter


Motion Blur (according to Wikipedia) is when the previous frame (or an accumulation of

previous frames) is blended over the current frame to create a blurring effect of Object in

motion.



system.kGPUCapabilityVelocityBlurFilterSupport

This Constant holds a boolean value denoting whether the GPU has Velocity Blur Filter


Velocity Blur is almost identical to Motion Blur, but is based on the speed of the Object, not

just whether it is motion.

system.kGPUCapabilityContrastFilterSupport

This Constant holds a boolean value denoting whether the GPU has Contrast Filter


A Contrast Filter is used to dynamically adjust the Contrast during the rendering of a Scene.

system.kGPUCapabilityHardwareOcclusionSupport

This Constant holds a boolean value denoting whether the GPU has Hardware Occlusion


See application.kOptionHardwareOcclusion for more details on Hardware Occlusion.

system.kOSTypeAngstrom

This Constant holds a boolean value denoting whether the Operating System is an Angstrom

OS, or not.

system.kOSTypeAndroid

This Constant holds a boolean value denoting whether the Operating System is an Android

OS, or not.



USER

hUser = user.getLocalSoundSourceObject ( hUser )

Call this Function to obtain a Handle to the Sound Object for a specified User (by the “hUser”

Parameter). This Function returns a Handle.

nDistance = user.getLocalSoundSourceReferenceDistance ( hUser )

Call this Function to obtain the Reference Distance for the Sound Object for a specified User

(by the “hUser” Parameter). This Function returns a numeric value (between 0 & ∞).

nFactor = user.getLocalSoundSourceRolloffFactor ( hUser )

Call this Function to obtain the Roll-off Factor for the Sound Object for a specified User (by

the “hUser” Parameter). This Function returns a numeric value (between 0 & ∞).

bOK = user.setLocalSoundSourceObject ( hUser, hObject )

Call this Function to set a specified Sound Object (by the “hObject” Parameter) for a

specified User (by the “hUser” Parameter). This Function returns "True" if the specified

Sound Object is set successfully, or “False” otherwise.

bOK = user.setLocalSoundSourceReferenceDistance ( hUser, nDistance )

Call this Function to set a specified Reference Distance (by the “nDistance” Parameter – a

numeric value between 0 & ∞) for the Sound Object of a specified User (by the “hUser”

Parameter). This Function returns “True” if the specified Reference Distance is set


bOK = user.setLocalSoundSourceRolloffFactor ( hUser, nFactor )

Call this Function to set a specified Roll-off Factor (by the “nFactor” Parameter – a numeric

value between 0 & ∞) for the Sound Object of a specified User (by the “hUser” Parameter).

This Function returns “True” if the specified Roll-off Factor is set successfully, or “False”

otherwise.



XML

bOK = xml.receive ( hXML, sURI, sOptionalHeader )

Call this Function to receive a specified XML file (by the “hXML” Parameter) from a specified

URI (by the “sURI” Parameter – a string value) with an optional XML Header (by the

“sOptionalHeader” Parameter – a String value). This Function returns “True” if the file is

received successfully, or “False” otherwise.