Add Lua Function (addLuaFunction)

The Lua Bind Function example demonstrates the following:

• How to add a new Lua function that can be used with scripted tasks.
• How to use luabind to bind classes and class methods to Lua scripts.
• How to add objects that can be referenced in Lua scripts.
• How to write a plugin that can be used with a back-end.

The Add Lua Function example adds a new Lua bound function called luaExamplePrintMessage and a new object example that can reference this call in a Lua script as example:luaExamplePrintMessage.

Since this example is loaded as a plugin, it can be used in conjunction with the released VR-Forces application. Make sure to enable the addLuaFunction example from the launcher application.

Usage

In the Launcher, click the Plug-ins button to bring up the Plug-ins Selection dialog. Enable the plugin. Then launch VR-Forces.

To view the new behavior:

1. Create a new Scenario
2. Create a new scripted task. Scripted tasks are accessed from the Simulation menu item.
3. Edit the script for the scripted task
4. In the init method place a call to example:luaExamplePrintMessage("Hello World!").
5. Create an entity, bring up the entity information window and set the notify level to Info.
6. Task the entity to perform the new scripted task.
7. The entity information window and the back-end console window should display Hello World!

Lua Scripting Documents

Documentation of Lua functions for scripted tasks has its own help system.

Plugin Entry Points

/*******************************************************************************
** Copyright (c) 2012 MAK Technologies, Inc.
** All rights reserved.
*******************************************************************************/

//VR-Forces includes
#include "vrfcgf/vrfPluginExtension.h"
#include "vrfLua/luaScriptInterfaceImpl.h"
#include "vrfLua/luaObjectSerializer.h"
#include "vrfobjcore/vrfObject.h"
#include "luabind/out_value_policy.hpp"

class AddLuaFunctionInterfaceExtension : public DtLuaScriptInterfaceExtension
{
public:
   AddLuaFunctionInterfaceExtension()
   {
   }

   virtual ~AddLuaFunctionInterfaceExtension()
   {
   }

   // Creator function.
   static DtLuaScriptInterfaceExtension* create(void* usr)
   {
      // In this example, the usr pointer is unused.
      return new AddLuaFunctionInterfaceExtension;
   }

   virtual void printMessage(const std::string& message)
   {
      DtWarn << myEntity->markingText().string() << ": " << message.c_str() << std::endl;
      myEntity->objectConsoleInfo() << message << std::endl;
   }

   virtual std::string multipleReturn(bool b, int& someNumber, bool& success)
   {
      if (b)
      {
         someNumber = 40;
         success = true;
      }
      else
      {
         someNumber = 10;
         success = false;
      }
      return "return string";
   }

   bool alreadyInitialized(lua_State* L, const char* moduleName) const
   {
      luabind::object obj = luabind::globals(L)["example"];

      if (luabind::type(obj) != LUA_TNIL)
      {
         return true;
      }

      return false;
   }

   virtual void bindLuaFunctions(DtVrfObject* entity, const DtString& scriptId,
      lua_State* L)
   {
      // Since this initialization get called twice in some instances (due to lua table changes when loading a scenario)
      // check to make sure this is not already initialized
      if (alreadyInitialized(L, "example"))
      {
         return;
      }

      myEntity = entity;

      luabind::module(L)
         [
            luabind::class_<AddLuaFunctionInterfaceExtension>("AddLuaFunctionInterfaceExtension")
               .def("luaExamplePrintMessage", 
                  &AddLuaFunctionInterfaceExtension::printMessage)
               .def("luaExampleMultiReturn", &AddLuaFunctionInterfaceExtension::multipleReturn,
                      luabind::pure_out_value(_3) + luabind::pure_out_value(_4))
         ];

      luabind::globals(L)["example"] = this;
      
      DtLuaObjectSerializer::instance()->addKeyToIgnore("example");
   }

protected:
   DtVrfObject*   myEntity;
};

extern "C" {

   DT_VRF_DLL_PLUGIN void DtPluginInformation(DtVrfPluginInformation& info)
   {
      info.pluginName = "addLuaFunction";
      info.pluginDescription = "An example of how to add a lua script function";
      info.pluginVersion = "1.00";
      info.pluginCreator = "MAK Technologies";
      info.pluginCreatorEmail = "sales@mak.com";
      info.pluginContactWebPage = "www.mak.com";
      info.pluginContactMailingAddress = "10 Fawcett Street, Suite 204, Cambridge, MA 02138 USA";
      info.pluginContactPhone = "(617) 876 8085";
   }

   DT_VRF_DLL_PLUGIN bool DtPostInitializeVrfPlugin(DtCgf* cgf)
   {
      DtLuaScriptInterfaceImpl::addLuaScriptInterfaceExtension(AddLuaFunctionInterfaceExtension::create, 0);
      return true;
   }

   DT_VRF_DLL_PLUGIN void DtUnloadVrfPlugin()
   {
      DtLuaScriptInterfaceImpl::removeLuaScriptInterfaceExtension(AddLuaFunctionInterfaceExtension::create, 0);
   }
}