User Script File Reference

This section contains reference information for the user script file. Below is all message response functions list. These functions will be executed by Scene Player when some event happen (e.g. user press a key or click mouse button). In User Script File, all script codes which outside these functions  will be executed once when loading scene file.

Keyboard Input Messages:

 Function Name  Parameter  Return  Explain
 OnKeyDown number nChar None

The framework calls this member function when a nonsystem key is pressed. A nonsystem key is a keyboard key that is pressed when the ALT key is not pressed or a keyboard key that is pressed when the window has the input focus.

Parameters

nChar
Specifies the virtual-key code of the given key.

Example

function OnKeyDown(nChar)
      local c=string.char(nChar)
      print(c)
      if (VK_UP==nChar) then
           print('up arrow key')
      elseif (VK_DOWN==nChar) then
           print('down arrow key')
      end
end
 OnKeyUp number nChar None The framework calls this member function when a nonsystem key is released. A nonsystem key is a keyboard key that is pressed when the ALT key is not pressed or a keyboard key that is pressed when the window has the input focus.

Parameters

nChar
Specifies the virtual-key code of the given key.

 
 OnChar number nChar None The framework calls this member function when a keystroke translates to a nonsystem character. This function is called before the OnKeyUp member function and after the OnKeyDown member function are called. OnChar contains the value of the keyboard key being pressed or released.

Parameters

nChar
Contains the character code value of the key.

Example

function OnChar(nChar)
      local c=string.char(nChar)
      print(c)
end
 OnKillFocus None None The framework calls this member function immediately before losing the input focus.
 OnSetFocus None None The framework calls this member function after gaining the input focus.

 

Mouse Input Messages:

 Function Name  Parameter  Return  Explain
 OnMouseMove number x, y number  The framework calls this member function when the mouse cursor moves.

Parameters

x, y
Specifies the x- and y-coordinate of the cursor. These coordinates are always relative to the upper-left corner of the window.
 OnMouseWheel number delta number  The framework calls this member function as a user rotates the mouse wheel and encounters the wheel's next notch.

Parameters

delta
Indicates distance rotated. The delta value is expressed in multiples or divisions of WHEEL_DELTA, which is 120. A value less than zero indicates rotating back (toward the user) while a value greater than zero indicates rotating forward (away from the user). The user can reverse this response by changing the Wheel setting in the mouse software.

 
 OnLButtonDown number x, y number  The framework calls this member function when the user presses the left mouse button.

Parameters

x, y
Specifies the x- and y-coordinate of the cursor. These coordinates are always relative to the upper-left corner of the window.

 
 OnLButtonUp number x, y number  The framework calls this member function when the user releases the left mouse button.
 OnLButtonDblClk number x, y number  The framework calls this member function when the user double-clicks the left mouse button.
 OnRButtonDown number x, y number  The framework calls this member function when the user presses the right mouse button.
 OnRButtonUp number x, y number  The framework calls this member function when the user releases the right mouse button.
 OnRButtonDblClk number x, y number  The framework calls this member function when the user double-clicks the right mouse button.
 OnMButtonDown number x, y number  The framework calls this member function when the user presses the middle mouse button.
 OnMButtonUp number x, y number  The framework calls this member function when the user releases the middle mouse button.
 OnMButtonDblClk number x, y number  The framework calls this member function when the user double-clicks the middle mouse button.

Remark:
All mouse input message functions returns a number.
If the return number is zero, the framework will continue process message.
If the return number is nonzero, the framework will give up farther process.

 

Window Messages:

 Function Name  Parameter  Return  Explain
 OnActivate number
nActive, nMinimized		 None The framework calls this member function immediately both the window being activated and the window being deactivated.

Parameters

nActive
Specifies whether the window is being activated or deactivated. A nonzero value indicates the window is activated; otherwise is deactivated.

nMinimized
Specifies the minimized state of the window being activated or deactivated. A nonzero value indicates the window is minimized.
 OnSize number type, cx, cy None This function is called after the window size has changed.

 

Application Flow:

 Function Name  Parameter  Return  Explain
 FrameMove None None This function is called before rendering every frame picture.
 Render2D draw2d None This function is called after rendering scene. You can only draw 2D content in this function.
 Render3D draw3d None This function is called after rendering scene. You can only draw 3D content in this function.
 OnRestoreDevice None None This function is called after restoring device. see Remark 2.
 UpdateUserInput userinput None This function is called after system inputting. see Remark 3.

Remark 1:

The calling sequence of these function is:

FrameMove Scene Rendering Render3D Render2D


Remark 2:

The D3D device and correlative objects will be restored when resizing window, loading scene, etc. While restoring, all device dependent resources (like textures, shader texts, etc) will be reloaded. So the OnRestoreDevice is the right place to do some setting for those resources. For example, assume a shader text include several techniques, when restoring it, the device will active the first valid technique; but you can active special technique to override device's choice.

Remark 3:

System collect all input device's events, then translate to input commands which stored in the userinput table. In the UpdateUserInput function, you can custom your own inputting by modifying the userinput table. The process flow of inputting is:

Collect device events Translate to input commands call UpdateUserInput() Update world by input commands