Script Function Reference

This section contains reference information for the script global functions provided by Awakening.

Sort

 Function Name  Parameter  Return  Explain

App

GetVersion None string Get the Scene Player's version as a string formated by "x.x.x.x". The first two numbers is determinant, and the last two numbers usually for weak update like bug repair.

For example:
string "2.5.0.3" indicates the product edition is 2.5, and 0,3 only for update.
GetMainWnd None dword Get window handle of scene player
GetAppPath None string Get application path. For stand alone player, return .exe file's folder path; for web player, return user's home path.
GetAppTime None number Get the number of seconds that have elapsed since the Scene Player start. It's affected by play speed , not the real system time.
GetFrameTime None number Get current shot time, namely number of seconds that have elapsed since shot start.
SetFrameTime number None Set current shot time
IsWeb3D None boolean Whether playing in web3d mode
IsFullScreen None boolean Whether playing in fullscreen mode
FullScreen boolean FullScreen
[number Width, Height]
None Toggle full screen mode on and off, also can assign fullscreen mode's width & height
GetFullScreenMode [number ModeIdx] 1. None
2. number ModeNum
3. number Width, Height
if no parameter, return Full Screen Mode Number of current 3D device;
if ModeIdx < 1, return current display mode's width & height;
if ModeIdx >=1  and ModeIdx < =ModeNum, return the specified mode's width & height;
if failed, return nil .
IsPause None boolean Whether scene was paused
Pause boolean pause None Pause scene
IsEnableAccel None boolean Whether enable accelerator keys
EnableAccel boolean enable boolean Enable/Disable accelerator keys, return previous value
IsEnableContextMenu None boolean Whether enable context menu.
(only web3d player has context menu)
EnableContextMenu boolean enable boolean Enable/Disable context menu, return previous value
GetInputStyle None dword Get input style; see Input Style.
SetInputStyle dword dword Set input style, return previous value
Exit None None Exit program (do nothing in web player)
NoHardwareVP boolean bNoHWVP boolean   Disable hardware vertex processing , return previous value
( only valid in Scene Config File & windsplayer.cfg )
VerticalSync boolean bVSync boolean   Toggle vertical sync, return previous value
( only valid in Scene Config File & windsplayer.cfg  )
MultisampleType number nSamples None Set levels of multisampling ( only valid in Scene Config File & windsplayer.cfg ).
If the 3d device cann't achieve the required quality, then will use the most approaching level.

Parameters:
nSamples (0~16):  multi-sample type

GetVertexShaderVer boolean bBaseCaps number major, minor Get vertex shader version, indicating the level of vertex shader supported by the device. Return two numbers that represent the vertex shader main and sub versions.

Parameters:

bBaseCaps : true for get base device VS version; false/absence for get current device VS version.

see Remark 1.

GetPixelShaderVer None number major, minor Get pixel shader version, return two numbers that represent the pixel shader main and sub versions.
NoStopSound boolean bNoStop boolean   Do not stop sound when scene close, return previous value
Unpack string packagefile boolean   Unpack web3d scene package
GetTempFileName None string tempfile Creates a name for a temporary file. 
GetPackageInfo string url, destfile string path, scenefile, version Retrieves scene information from a package. You need to unpack downloaded scene package before calling this function.

Parameters:

url:

The scene pakcage's remote address.

destfile:

The destination file name of download.

Return Value:

path:

The folder name of scene file.
(e.g. c:\temp\painter )

scenefile:

The file name of scene file.
(e.g. painter.sce )

version:

The required scene player version.
(e.g. 3.0.0.0 )

Remark:

The full file name of scene file is:

 path  +   \   +   scenefile

(e.g. c:\temp\painter\painter.sce )

GetBasePath None string basepath Retrieves the base path, also resource path.
SetBasePath string basepath boolean Set the base path, also resource path. Program will prefix the base path to all file paths which started with ' \ ' , to get full resource file path.

Option

LimitFPS boolean LimitFPS boolean   Switch Limit FPS, return previous value
PlayerSize number
BodyWidth, DuckHeight, StandHeight, EyeOffset
number
BodyWidth, DuckHeight, StandHeight, EyeOffset
Set player size, return previous value
FovViewDistance number
FOV, NearPlane, FarPlane
number
FOV, NearPlane, FarPlane
Set FOV and view distance, return previous value
CameraMoveRotateStep number
MoveStep, RotateStep
number
MoveStep, RotateStep
Set camera movement, return previous value
CameraMovementSwitch boolean
ArcBallEnable, MoveEnable, RotateEnable
boolean
ArcBallEnable, MoveEnable, RotateEnable
Set camera movement, return previous value
GameMode boolean GameMode (false means free view mode) None Switch Free View Mode
IsGameMode None boolean   Whether in Free View Mode
ZeroGravity boolean ZeroGravity boolean   Switch Zero Gravity, return previous value
RenderShadow boolean shadow boolean Whether render dynamic shadow, return previous value
GetBlurEffect None number Get blur effect setting.
0: No Blur Effect
1: 1X Blur Effect
2: 2X Blur Effect
BlurEffect number Blur (0: None, 1: 1X, 2: 2X) number Set blur effect, return previous value
Speed number Speed ( 0.125 ~ 32 ) number Set play speed, return previous value
GetHDRMode None number Get HDR Mode.
0: X8R8G8B8
1: A16B16G16R16F
2: A16B16G16R16
3: A8R8G8B8
HDRMode number None Set HDR Mode

Scene

LoadScene string SceneName, ShotName number Load scene file and play assigned shot, return:
0: failed 1: successed, 2: will load scene after next FrameMove()
see Remark 2.
SaveScene string SceneName boolean Save current scene to file.
GetShotTimeLength [string ShotName] number Get assigned shot's time length, if failed, return 0; if the ShotName is absent, get current shot's time length.
PlayShot string ShotName boolean Play assigned shot, if failed, return false, otherwise return true.
IsPlayingShot None boolean Whether playing shot
GetPlayingShot None nil or shot Get the playing shot, return nil if no playing shot.
StopShot None None Stop shot
PlayAnimate string ShotName boolean Play assigned shot as animate mode ( not effect camera )
IsAnimatePlaying string ShotName nil or boolean Whether the assigned shot is playing; if no shot match the name, return nil .
StopAnimate string ShotName boolean Stop assigned shot, if failed, return false, otherwise return true.
PlaySound string SoundName
number Volume = -100
[boolean MusicMode]
boolean Play assigned sound (music), if failed, return false, otherwise return true.

The Volume allowable values are between 0 (no attenuation) and -10,000 (silence); the scale is logarithmic. If the parameter Volume is absent, use the default value (-100).

If the assigned sound is not found in sounds list:

1. when MusicMode is false (default), then the function will try to load wav data form file.
2. when MusicMode is true, then the function will try to load music data form file.

If call this function with no parameter, will stop all wav sounds

GetMusicVolume None number   Gets the volume of the playing music
SetMusicVolume number   None Sets the volume of the playing music
IsPlayingMusic None boolean Whether playing music
StopMusic None None Stop music
DoScript string ScriptName boolean Execute assigned script, if failed, return false, otherwise return true.
GetURL string URL None Open browser to visit assigned URL
GetAvailableVideoMem None number   Returns an estimate of the amount of available video memory (MB).
DoConsoleCommand string command boolean Do console command.
example: DoConsoleCommand('r_shadow 0') --turn off projected shadow
GetConsoleVar string var nil or number Retrieves the value of the specified console variable, if variable is not found, return nil.
GetSceneCenter None vec Get the center position of scene
In ArcBall mode, camera will moves circle the center position.
SetSceneCenter vec None Set the center position of scene
GetSelectionHead string selection dword pos Get objects of assigned selection
GetSelectionNext dword pos dword handle,
dword pos,
dword classid
Get objects of assigned selection, see Remark 3.
Returned classid listed in udhead.

Util

WorldToScreen vec vec Convert the world coordinates of a specified point (3D) to screen (2D) coordinates.
ScreenToWorld vec vec Convert the screen coordinates of a specified point (2D but have Z depth) to world coordinates.
GetRayFromPoint number x, y ray Return a ray that start from assigned screen point, emit along camera direction.
RayIntersectTriangle vec org, dir, a,b,c
[ boolean checkBackface ]
boolean intersect,
number t, u, v
Check intersection between ray and triangle. The parameter org, dir define the ray, a,b,c are vertices of triangle, C.W. order; and checkBackface indicates whether check back side of triangle, default is false.
Returned intersect indicates whether intersecting; t is distance to intersection point; the intersection point can be calculated by:
org + dir * t   or  (1 - u - v )*a + u * b + v * c
MatrixToYawPitchRoll matrix number y, p, r Convert matrix to Euler angles, returns yaw, pitch, roll. 
VectorToYawPitch vec number y, p, Convert normalized vector to Euler angles, returns yaw, pitch
ModifyStyle dword
style, remove ,add
dword Modify a dword style value. Pass a initial style value, do remove & add styles, return the modified style value.
PerlinNoise number x [ , y ] number A Perlin Noise function, supports 1D or 2D.
Output range is about -1.0 to 1.0.
DWORDtoColor dword color Convert a dword value to color
ColortoDWORD color dword Convert a color to dword
DWORDtoRGBA dword number r, g, b, a Pickup color values from a dword, then return four numbers: r, g, b, a (value range is 0-1)
RGBAtoDWORD number r, g, b, a dword Pack r, g, b, a into a dword
toDWORD 1. string snum
2. number num
dword 1. Convert a string of hex-number to a dword.
e.g. toDWORD('FF88AA9C') will return a dword that have value FF88AA9C
2. Convert a number to a dword.
e.g. toDWORD( 255 ) will return a dword that have value 000000FF
( Attention: number is a single precision float, so it's not accurate for big number )
1. string hiWord, lowWord
2. number hiWord, lowWord
3. string hi, number  low
4. number  hi, string low
dword  Convert & unite a high-order word and a low-order word to a dword
e.g. toDWORD('FF88', 'aa9c') will return a dword that have value FF88AA9C; toDWORD('FF88', 255) will return a dword that have value FF8800FF
notDWORD dword dword Perform Bitwise-NOT arithmetic to a dword
andDWORD dword num, ... dword Perform Bitwise-AND arithmetic to one or more dword numbers, return a dword
orDWORD dword num, ... dword Perform Bitwise-Inclusive-OR arithmetic to one or more dword numbers, return a dword
xorDWORD dword num, ... dword Perform Bitwise-Exclusive-OR arithmetic to one or more dword numbers, return a dword
lshiftDWORD dword dw, number  num dword Perform Bitwise-Left Shift arithmetic to a dword
rshiftDWORD dword dw, number  num dword Perform Bitwise-Right Shift arithmetic to a dword
print ... None Incept one or more parameters (can be any data-type), convert them to string then output a line to scene player's console.
AnsiToUnicode string ansi nil or string Converts a ANSI string to a UTF-16 (wide character) string.
UnicodeToAnsi string unicode nil or string Converts a UTF-16 (wide character) string to ANSI string.

Remark 1:  Because D3D provides a software simulation for Vertex Shader, so VS may has different version number under software vertex processing and hardware vertex processing. To get real VS version supported by the hardware device, you must call the GetVertexShaderVer function while the Scene Player enable hardware vertex processing; but you can't freely switch between hardware & software vertex processing when the Scene Player running, so the bBaseCaps parameter comes for getting basic VS version, the basic VS version is the lowest version number within a Scene Player running period.

Remark 2: If you call LoadScene() in function FrameMove(), it executes immediately; otherwise, the execution will delay to next FrameMove.

Remark 3: You can use below codes to get objects in Selection :

local selectionName = 'walls'    -- replace "walls' to your selection name
local pos = GetSelectionHead(  selectionName  )
while pos do
    local root, cid
    root, pos, cid = GetSelectionNext( pos )
    root = ObjectFromClassID( cid, root )
    if root then print( root.getName() ) end
end