Added a lua function "convert" to convert a userdata value to another gameplay class type.

The purpose of this function is convert a Control to a Button, or PhysicsCollisionObject to a PhysicsRigidBody.
This function will change the meta table of the userdata value to the meta table of the class with the given name.

gameplay/src/ScriptController.cpp

@@ -692,6 +692,7 @@ void ScriptController::initialize()
 
 #ifndef NO_LUA_BINDINGS
     lua_RegisterAllBindings();
+    ScriptUtil::registerFunction("convert", ScriptController::convert);
 #endif
 
     // Create our own print() function that uses gameplay::print.
@@ -954,6 +955,41 @@ ScriptController::ScriptCallback ScriptController::toCallback(const char* name)
         return ScriptController::INVALID_CALLBACK;
 }
 
+int ScriptController::convert(lua_State* state)
+{
+    // Get the number of parameters.
+    int paramCount = lua_gettop(state);
+    // Attempt to match the parameters to a valid binding.
+    switch (paramCount)
+    {
+        case 2:
+        {
+            if (lua_type(state, 1) == LUA_TUSERDATA && lua_type(state, 2) == LUA_TSTRING )
+            {
+                // Get parameter 2
+                const char* param2 = ScriptUtil::getString(2, false);
+                if (param2 != NULL)
+                {
+                    luaL_getmetatable(state, param2);
+                    lua_setmetatable(state, -3);
+                }
+                return 0;
+            }
+
+            lua_pushstring(state, "lua_convert - Failed to match the given parameters to a valid function signature.");
+            lua_error(state);
+            break;
+        }
+        default:
+        {
+            lua_pushstring(state, "Invalid number of parameters (expected 2).");
+            lua_error(state);
+            break;
+        }
+    }
+    return 0;
+}
+
 // Helper macros.
 #define SCRIPT_EXECUTE_FUNCTION_NO_PARAM(type, checkfunc) \
     int top = lua_gettop(_lua); \

gameplay/src/ScriptController.h

@@ -884,6 +884,32 @@ private:
      */
     static ScriptController::ScriptCallback toCallback(const char* name);
 
+    /**
+     * Converts a Gameplay userdata value to the type with the given class name.
+     * This function will change the metatable of the userdata value to the metatable that matches the given string.
+     * 
+     * Example:
+     * <code>
+     * local launchButton = form:getControl("launch")
+     * convert(launchButton, "Button")
+     * print("Button text: " .. launchButton:getText())
+     * </code>
+     * 
+     * <code>
+     * -- The signature of the lua function:
+     * -- param: object    A userdata object that represents a Gameplay object.
+     * -- param: className The name of the class to convert the object to. (Examples: "Button", "PhysicsRigidBody")
+     * function convert(object, className)
+     * </code>
+     * 
+     * @param state The Lua state.
+     * 
+     * @return The number of values being returned by this function.
+     * 
+     * @script{ignore}
+     */
+    static int convert(lua_State* state);
+
     // Friend functions (used by Lua script bindings).
     friend void ScriptUtil::registerLibrary(const char* name, const luaL_Reg* functions);
     friend void ScriptUtil::registerConstantBool(const std::string& name, bool value, const std::vector<std::string>& scopePath);