Warning: This tutorial is only viable for games using the Lua script, it doesn’t work for games exported in native code, because it uses LUA elements

Introduction

You can add default values in a metatable when declaring it.
The syntax is this one:

local myMetatable = {"value0", 32, hObject}

All the elements between the { } are the value, and the key is set automatically using an index, starting at 0.
Here, myMetatable[0] is “value0″, myMetatable[1] is 32 and myMetatable[2] is hObject

It’s exactly the same result than the code was:

local myMetatable = {}
myMetatable[0] = "value0"
myMetatable[1] = 32
myMetatable[2] = hObject

Sample

Below, you can find a small function using this kind of declaration:

--------------------------------------------------------------------------------
function MyGame.getMonthName ( nMonth )
--------------------------------------------------------------------------------
 
    local month_of_year = {"January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"}
    return month_of_year[nMonth]
 
--------------------------------------------------------------------------------
end
--------------------------------------------------------------------------------

Call it with a month index, and you’ll get the month name.

Introduction

Metatables in LUA are a kind of hashtable. You can associate a key and a value. Here, the key can be anything (number, string, object…)
The URL post parameters is a list of “parameter_key=parameter_value”, separated by “&”.
We will use the parameter_keys as key of a metatable, and parameter_values as value.

Steps

1. In your game, where you want to create an url, declare the metatable like that:

local params = {}

2. Now, add all the parameters you want for your URL by adding each key and value of the parameter in the metatable, using this syntax:

params["page"]=""..this.nCurrentPage ( )
params["category"]=this.sCurrentCategory ( )

3. Create a function buildPost ( params ), taking in argument your metatable containing the URL parameters.
4. Start by declaring the result variable:

local sRes = ""

5. We will now create a loop for the metatable. For this kind of table, you mustn’t use the “for i” loop, but the “for each” one.
The syntax of this loop is:

for vKey in params
do
    local vValue = params[vKey]
 
end

6. Concat the key and the value, by adding a “=” between them. Do not forget to encode the value. Then add the param to the sRes variable.

local sParam = vKey.."="..string.encoreURL ( vValue )
sRes = sRes..sParam.."&"

7. At the bottom of the function, do not forget to remove the last “&”, and return the final string:

sRes = string.getSubString ( sRes, 0, string.getLength ( sRes ) - 1 )
return sRes

The whole function should now looks like that:

--------------------------------------------------------------------------------
function Facebook.buildPost ( params )
--------------------------------------------------------------------------------
 
    local sRes = ""
    for vKey in params
    do
        local vValue = params[vKey]
        local sParam = vKey.."="..string.encoreURL ( vValue )
 
        sRes = sRes..sParam.."&"
    end
 
    sRes = string.getSubString ( sRes, 0, string.getLength ( sRes ) - 1 )
    return sRes
 
--------------------------------------------------------------------------------
end
--------------------------------------------------------------------------------

8. Get back to the place where you have declared the metatable, and add this line:
local sUrl = this.sTheServerUrl ( )..”/search?”..this.buildPost ( params )

You can now use the url

Conclusion

By using this way, you can now easily build URLs in your game, just by creating a metatable, adding the post parameters in it and calling your buildPost function.

Steps

The idea is to make some StoneScript functions pointing to custom Lua functions.

1. Create an AIModel “DeviceSimulator”

2. Create a function named getOSType, in which you return the constant of the OS type you want to simulate:

return system.kOSTypeAndroid

3. Create a function named getClientType that return the constant of the client type you want to simulate:

return system.kClientTypeEmbedded

4. Create a onInit handler in the AI, and override the lua pointers for both system.getOSType and system.getClientType functions by your own ones:

if ( system.getClientType ( ) == system.kClientTypeEditor )
then  
    system.getOSType = this.getOSType
    system.getClientType = this.getClientType
end

5. Compile your AIModel. You will get this error:
“malformed expression, expected ‘(‘”
You can ignore this error, the script will work.

6. Place the AIModel in your User Main AIs of your game, and be sure to place it on the very top (for the onInit of the AIModel to be executed before anything else)

Conclusion

Now, anywhere in your code, when you will call system.getOSType ( ) or system.getClientType ( ), it will call your own functions, returning the constant of your choice.
For instance, in that case, when calling system.getOSType ( ), you will get system.kOSTypeAndroid, even if you are in ShiVa Editor.

This is a very useful usage of the Lua Pointers.
Many powerful things can be done by going deeper than only using the “basic” Lua scripting.

1. Create an AIModel named « ButtonsManager », and add it to your game User Main AIs.

2. Create 2 hashtables to store the textures of your buttons, one for the state « normal » and one for the state « pressed ».

3. Create a string variable named « sUnderMouseButton » to store the button that has been clicked.

4. Create a function to simplify the setup of the buttons. The function take in parameter the tag of the button, and its textures for both states. Then, the function adds the textures in our 2 hashtables, using the component tag as key. The function should looks like that :

--------------------------------------------------------------------------------
function ButtonsManager.addButton ( sComponent, sTextureNormal, sTexturePressed )
--------------------------------------------------------------------------------
 
    if ( sTextureNormal )
    then
        hashtable.add ( this.htButtonsNormal ( ), sComponent, sTextureNormal )
    end
    if ( sTexturePressed )
    then
        hashtable.add ( this.htButtonsPressed ( ), sComponent, sTexturePressed )
    end
 
--------------------------------------------------------------------------------
end
--------------------------------------------------------------------------------

5. Create the onInit handler, and add the button you want to interact with, by using the function you have created above :

--------------------------------------------------------------------------------
function ButtonsManager.onInit (  )
--------------------------------------------------------------------------------
 
	this.addButton ( "Menu.PlayButton", "play_button_normal", "play_button_pressed" )
	this.addButton ( "Menu.OptionsButton", "options_button_normal", "options_button_pressed" )
	this.addButton ( "Menu.CreditsButton", "credits_button_normal", "credits_button_pressed" )
 
--------------------------------------------------------------------------------
end
--------------------------------------------------------------------------------

6. Create a new function to update the state of a button. The function takes the button tag and the button state as parameters. Create 2 local variables for the 2 possible states the button can have. These variables will be used as constants. The button state in parameter must match one of the constants.

--------------------------------------------------------------------------------
function ButtonsManager.setButtonTexture ( sButtonTag, kButtonState )
--------------------------------------------------------------------------------
 
    local hButton = hud.getComponent ( application.getCurrentUser ( ), sButtonTag )
    if ( hButton )
    then
        local kButtonStateNormal = 0
        local kButtonStatePressed = 1

Then, get the texture name corresponding to the wanted button state, and update the button texture :

        local sTexture
        if ( kButtonState == kButtonStateNormal )
        then
            sTexture = hashtable.get ( this.htButtonsNormal ( ), sButtonTag )
        elseif ( kButtonState == kButtonStatePressed )
        then
            sTexture = hashtable.get ( this.htButtonsPressed ( ), sButtonTag )
        end
        if ( sTexture )
        then
            hud.setComponentBackgroundImage ( hButton, sTexture )
        end
    end
 
--------------------------------------------------------------------------------
end
--------------------------------------------------------------------------------

7. Add the onMouseButtonDown handler to your AI. When this handler is being called, if a button is under the cursor, you have to change its texture (from normal to pressed). Start by checking which component is under the mouse cursor, and if this component is a button. If it’s the case, store the button tag in the sUnderMouseButton variable, to be able to restore its previous texture when the mouse button will be released.

--------------------------------------------------------------------------------
function ButtonsManager.onMouseButtonDown ( nButton, nPointX, nPointY, nRayPntX, nRayPntY, nRayPntZ, nRayDirX, nRayDirY, nRayDirZ )
--------------------------------------------------------------------------------
 
    local hComponent = hud.getUnderCursorComponent ( application.getCurrentUser ( ) )
    if ( hComponent and hud.getComponentType ( hComponent ) == hud.kComponentTypeButton )
    then
        local sButtonTag = hud.getComponentTag ( hComponent )
        this.sUnderMouseButton ( sButtonTag )

And then, update the component texture by calling the setButtonTexture function you have created a few minutes ago, using the right button state contant :

        local kButtonStateNormal = 0
        local kButtonStatePressed = 1
 
        this.setButtonTexture ( this.sUnderMouseButton ( ), kButtonStatePressed )
    end
 
--------------------------------------------------------------------------------
end
--------------------------------------------------------------------------------

8. Finally, create the onMouseButtonUp handler and restaure the button normal texture :

--------------------------------------------------------------------------------
function ButtonsManager.onMouseButtonUp ( nButton, nPointX, nPointY, nRayPntX, nRayPntY, nRayPntZ, nRayDirX, nRayDirY, nRayDirZ )
--------------------------------------------------------------------------------
 
    if ( not string.isEmpty ( this.sUnderMouseButton ( ) ) )
    then
        local kButtonStateNormal = 0
        local kButtonStatePressed = 1
 
        this.setButtonTexture ( this.sUnderMouseButton ( ), kButtonStateNormal )
        this.sUnderMouseButton ( "" )
    end
 
--------------------------------------------------------------------------------
end
--------------------------------------------------------------------------------

Conclusion

You can use this AIModel in all of your games, you only have to change the onInit content to match the buttons of your games.
Do not forget to reference all your buttons textures in your game (Game Editor > Resources tag).
This sample also works for a multitouch application.

Go further

You can add more features to this AIModel, in order to be able to change the button text color for instance.

Setup

To mix multitouch and mouse events, we will redirect the mouse events to multitouch handlers when the multitouch is off.
Create the mouse handlers (onMouseButtonDown, onMouseMove and onMouseButtonUp) and the multitouch handlers (onTouchSequenceBegin, onTouchSequenceChange and onTouchSequenceEnd ).

To know if the multitouch is enabled, add a variable bMultitouchEnabled in your AIModel and in a onInit handler, write the line:
this.bMultitouchEnabled ( input.enableMultiTouch ( this.getUser ( ), true ) )

You also have to add a variable bMouseDown to know if a mouse button is pressed.

Mouse events redirection

Now, you have to redirect mouse events to multitouch events when the multitouch is disabled.

onMouseButtonDown

In the onMouseButtonDown handler, set the bMouseDown variable to true and send an event to the onTouchSequenceBegin handler. Of course, this code has to be executed only if multitouch is disabled:

if ( not this.bMultitouchEnabled ( ) )
then
    this.bMouseDown ( true )
    this.sendEvent ( "onTouchSequenceBegin" )
end

onMouseButtonUp

The code is pretty the same for the onMouseButtonUp handler, but the event has to be sent to the onTouchSequenceEnd handler, and you have to set the mouse bMouseDown variable to false.

if ( not this.bMultitouchEnabled ( ) )
then
    this.bMouseDown ( false )
    this.sendEvent ( "onTouchSequenceEnd" )
end

onMouseMove

This handler will works like the 2 others, but have another restriction: the bMouseDown has to be true because on a multitouch device, it is not possible to interact with the screen without touching it, pressing the mouse button simulate the finger which is touching the screen.
You also have to pass the nPointX and nPointY parameters of the onMouseMove handler to the onTouchSequenceChange handler.

if ( not this.bMultitouchEnabled ( ) and this.bMouseDown ( ) )
then
    this.sendEvent ( “onTouchSequenceChange”, 1, nPointX, nPointY, -1, 0, 0, -1, 0, 0 )
end

The value “1” mean the touch n°0 is running. The two “-1” values mean the touch n°1 and n°2 are not running (refer the the onTouchSequenceChange to know all the parameters).

For this tutorial, you need to declare a table in your AIModel variables, I named it tTable.
create a function named getFile and add the variable sFileURL as parameter.

Get the path

Start the script by clearing the table data:
table.empty ( this.tTable ( ) )

Use now the string.explode. The delimiter will be the “/” character. Use the sFileURL variable plus “/” as first parameter, the table as second parameter, and “/” as delimiter (third parameter).
string.explode ( sFileURL..”/”, this.tTable ( ), “/” )

The last item of the table is the filename with its extension:

Get the filename and the extension

local sFilenameAndExtension = table.getLast ( this.tTable ( ) )

Logically, the path of the file is the URL without the file and the extension:
local sPath = string.getSubString ( sFileURL, 0, string.getLength ( sFileURL ) – string.getLength ( sFilenameAndExtension ) )

Now you have to separe the filename to its extension, you must find the “.” symbol:
local nDotIndex = string.findFirst ( sFilenameAndExtension, “.”, 0 )

The extension is the part at the right of the string:
local sExtension = string.getSubString ( sFilenameAndExtension, nDotIndex, string.getLength ( sFilenameAndExtension ) – nDotIndex )

And the filename is the other part:
local sFilename = string.getSubString ( sFilenameAndExtension, 0, string.getLength ( sFilenameAndExtension ) – string.getLength ( sExtension ) )

It is finished, you can return the results:
return sPath, sFilename, sExtension

An accelerometer track the forces applied on the device. When the device don’t move, the only force recorded is the gravity.

You have to consider that your device defines the center of a (x,y) space.
When the viewport is set to 0, the basis is in this orientation:

If you rotate the device, the basis rotates too, in the same direction.

In fact, the basis follow the iPhone rotation. When you will change the viewport rotation, the basis orientation will get an additional rotation (here +90°):

Script

Create a new AIModel named ViewportRotation, and create a variable named nOptionValue, type number. This variable will be used to store the current viewport rotation value. Add a onInit handler in which your set this variable to 0 and the viewport rotation to the same value:

Create now a onJoypadMove handler. The parameters we will use are nAxisX and nAxisY, corresponding to the position of the accelerometer on the x, y axis of the basis (don’t forget the accelerometer follow the gravity).

You can consider the device is enough rotated and the viewport has to changewhen the value of an axis is greater than 1.5 or lesser than -1.5,. In all the cases, you will add a value to the current rotation, and in all the cases, you have to modulate the result by 4, because the viewport rotation value is 0, 1, 2 or 3 (corresponding to the default rotation (0°) plus 1*90°, 2*90° or 3*90°).

When the device is the default position, the gravity force is on the Y axis only, in the negative side, but in this case, no need to change the viewport rotation because it is already the current one.

Rotation 180

When you rotate the device backward, the gravity is on the Y axis, in the positive side. At this moment, the needed viewport rotation is the opposite of the current one. To know the new viewport rotation, you have add 2 rotations of 90° (+2) on the current value (modulus 4).

Rotation 90

When you rotate the device on the right, the value of the gravity on the X axis become greater. When it is greater than 1.5, the viewport rotation has to be changed by the current value plus 1 rotation of 90° (+1) (modulus 4).

Rotation 270

When you rotate the device on the left, the viewport has to be rotated 3 times: the new value is the current value plus 3 rotation of 90° (+3) (modulus 4).

Of course, don’t forget execute the modulus and to apply the new viewport rotation at the end of the script.

You can see the full code here:

To solve this problem without making your script unreadable, I suggest you to create a function “addToHashtable” you will call, which will do automatically the check and add the key and in the hashtable if not existing, or only set the value in the other case.

The function take 3 parameters: the hashtable, the key and the value.

The code of the function is this one:

--------------------------------------------------------------------------------
function MyGame.addToHashtable ( htHashtable, sKey, vValue )
--------------------------------------------------------------------------------
 
   if ( hashtable.contains ( htHashtable, sKey ) )
   then
       -- If the key is in the hashtable, update the value
       hashtable.set ( htHashtable, sKey, vValue )
   else
       -- If the key is not in the hashtable, create a new entry in the hashtable, with sKey and vValue as key/value for this entry.
       hashtable.add ( htHashtable, sKey, vValue )
   end
 
--------------------------------------------------------------------------------
end
--------------------------------------------------------------------------------

You can call the function like that:

this.addToHashtable ( this.myHashtable ( ), “myKey”, 3 )

A popup is composed by a background and windows containing a title, a description and a button to close the popup.

The popup will be composed by 2 main HUD components: one for the background and a container to place and scale the popup window.
These 2 components will have a big Z-Order to appear in front of other HUDs of your game, and the background as to appear behind the window, their Z-Order will be 249 for the background and 250 for the window.

Platform setup

In ShiVa Editor, setup your desktop to have the HUD Editor and the scene viewer at the same time.
Define the resolution of the viewport as for an iPhone (in the Scene Viewer, click on Display>Size>iPhone>320×480:

Game setup

For this tutorial, you will need to have a game with a Main AIModel. In this AIModel, create a handler “onDestroyTemplateInstance”.
In this handler, add the parameter sTemplate, and write the script: hud.destroyTemplateInstance ( this.getUser ( ), sTemplate )

The Background

In the HUD Editor, create a new HUD template and create a new component, named Background, full size (100%x100%) and set the ZOrder to 249.
In the appearance section, set the background color to black and not at full opacity (ex: 0, 0, 0, 200). No border color (alpha: 0).

Create now 2 actions named appearBackground and disappearBackground:

In each action, add a command stopAction to stop the other one. (When the disappearBackground action will be called, it will stop the appearBackground action).

In the appearBackground action, add a command to interpolate the opacity to 255 on the Background component, in a linear way, during 250 ms. Add the same command in the disappearBackground action, but with an opacity of 0.

The window

Create now the container for the popup window. It has a full size (100%x100%) and a ZOrder at 250. In the appearance section, set the alpha of the background color and the border color to 0. Press OK to close the component edition.

Add now a child to this container as follow:

This component is the main window of the popup. Name it Window. It will contain the title of the window, the description and the exit button, so set its type to Container. Make it aspect ratio independant and size it to 50×31. Add a background image on it (the background of the popup) and check the background color, it must be 127, 127, 127, 255.

Title Label

Add the title, a label component, placed at the top of its container (Origin: top, position: 50-100), with a size of 100×25.
As it is a component used for writing text, It has no background color and no border color (alpha = 0) but a foreground color set to 127, 127, 127, 255 to have white text.
In the Label section, set a text to “This will be the title” for instance (it is just for text, it will be overwritten in another part of the tutorial) and the Text Height to 75.
You also have to choose a Font. To finish, set the Text Alignment to Center / Center

Description Label

Create another component in the Window container, type label, placed at 50-53 (origin Center) and with a size of 90×47.
It is a text component too, so set the alpha of the background and border color to 0 and set the foreground color to 127, 127, 127, 255.
In the Label section, add the text “There will be my description in this label”, choose the Font set the Text Height to 33 to have a text in 3 lines (100 / 33 >= 3).
Set the Text Alignment to Left / Center.

Close button

On the same container, add now a button component which will be used to close the popup.
Place it at the bottom (Origin Bottom, Position 50-6) and size it to 80×21.
The button will have a background image (BackColor to 127, 127, 127, 255) and a text (ForeColor to 127, 127, 127, 255).
No border color (alpha=0). In the Button section, add the text “OK”, set the Text Height to 65, the Text Alignment to Center / Center and choose a Font.

If you have done all the previous steps right, you should have this structure:

And the appearance like that:

Animation

Create now 2 actions named appear and disappear:

As for appearBackground and disappearBackground, add a stopAction in each action to stop the other one.

Appear

Edit the Container component and set its Visible state to false.

In the appear action, add a command SetSize on the Container component, to 0, 0, and then, another command to make it visible (SetVisible with true as parameter).

Add a CallAction command to call the appearBackground action, and set the Wait parameter to false.
Add now the final command, type InterpolateSize on the Container component, to the size 100×100, with a Spring2 effect during 1500 ms.

Note Wait parameter set to false for the CallAction to appearBackground will make both interpolations (InterpolateSize of the Container and InterpolateOpacity of the Background) to run at the same time.

Set now this action (appear) as the Initial Action.

Disappear

In the disappear action, call the disappearBackground action (add a CallAction command), with a Wait parameter at false and then, add a command to interpolate the size of the Container component (InterpolateSize command), to 0×0, with a linear animation, and during 200 ms.

Finally, add a command SendEventToUser, to the handler created at the beginning of this tutorial, onDestroyTemplateInstance, and set the first parameter type to String, and the value to “Popup”.

The action should be like that:

Congratulations, it is finish for the HUD Editor part, the HUD template should looks like that:

How to make it works?

In your game script, when you want to make your popup appearing, you have to create the template instance, and define the text of its title and description, for example:

As result, you have a beautiful window appearing in a very pleasant manner:

States suffice when you only have one xml to get, but when you want to load more than one file, or when you want to use states for another usage, it becomes difficult to use them for the xml.
With handlers, you only have to create a handler and an AI variable per xml to get.

Setup

Firstly, create a variable in your AIModel, named myXml1 in my case, type xml. Then created a handler (onGetMyXml1 for instance).
The handler will be called once when you will decide to get the xml file, and then, the handler will (down)load it and call itself until the xml is not received.

Test the status

At the beginning of the script, get the status of the xml variable:

<em>local status = xml.getReceiveStatus ( this.myXml1 ( ) )</em>

If the status is 1, it means the xml has been received and you can parse it.

if ( status == 1 )
then
     local root = xml.getRootElement ( this.myXml1 ( ) )
     --To do
else

I have written the first step of the parse process (get the root element), you now have replace the “–To do” by your own parse process, according to your xml structure.

In the other case, the xml hasn’t been received yet, and as I said previously, the handler will call itself while receiving the xml, so in the “else”, you have to put:

<em>this.postEvent ( 0, "onGetMyXml1" )</em>

Using the postEvent function with 0 as time parameter mean that the event will be executed at the next frame.
In that case, the status can be < 0 or 0<=status<1. If the status is lesser than 0, it means that the xml hasn’t been started or the receive process has failed, so you have to start the receive process:

if ( status < 0 )
then
   local sUrl = "http://www.myWebsite.com/myXml.xml"
   xml.receive ( this.myXml1 ( ), sUrl )
end

Of course, you have to replace the string sURL by your own URL.

Conclusion

Congratulations, you have finished this tutorial. Note there is no dedicated script when the status is >= 0 and < 1, because you just have to wait until the xml receive process ends, so the script will do nothing except calling the handler again at next frame.

If you have another xml, you just have to create a new xml variable, copy/paste your handler and change the variable name and the handler name in the postEvent function.
Don’t forget, you have to call each handler only one time on a onInit for example or when you want to receive the xml file.

You can see the fully code there:

--------------------------------------------------------------------------------
function myGame.onGetMyXml1 (  )
--------------------------------------------------------------------------------
 
local status = xml.getReceiveStatus ( this.myXml1 ( ) )
if ( status == 1 )
then
  local root = xml.getRootElement ( this.myXml1 ( ) )
   --To do
else
      if ( status < 0 )
      then
           local sUrl = "http://www.myWebsite.com/myXml.xml"
           xml.receive ( this.myXml1 ( ), sUrl )
      end
      this.postEvent ( 0, "onGetMyXml1" )
end
 
--------------------------------------------------------------------------------
end
--------------------------------------------------------------------------------