Add Lua Function (addLuaFunction)

Table of Contents

• Adding a New Lua Bound Function
• How to Run the Example
  • Usage
• Lua Scripting Documents
• Plugin Entry Points

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.

Adding a New Lua Bound Function

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.

How to Run the Example

Usage

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

To view the new behavior:

1. Start VR-Forces GUI and SIM.
2. Create a new Scenario - e.g. EntityLevel SMS on Ground_DB II terrain.
3. Create a new scripted task. Scripted tasks are accessed from the Simulation menu item - Simulation -> Scripts... Press New Script button within the Scripts dialog.
4. Set a script Name and Edit the lua script for the scripted task

5. In the init method, place a call to:

     example:luaExamplePrintMessage("Hello World!")
   

6. Press Add button within the Scripts dialog to add the new scripted task.
7. Close both the Edit script and the Scripts dialogs.
8. Create an entity, bring up the entity information dialog and set the notify level to Info.
9. Task the entity to perform the new scripted task.
10. The entity information dialog and the back-end console window should display the Hello World! message.

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/localObject.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->objectName().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(DtLocalObject* 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:
   DtLocalObject*   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);
   }
}