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

Select Settings, Plugins... and on the Plugins Editor page, use the combo box at the top of the page to select the plug-in. Then enable the Load.

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->objectName().c_str() << ": " << 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";
   }

   virtual void bindLuaFunctions(DtVrfObject* entity, const DtString& scriptId,
      lua_State* L)
   {
      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 = "150 Cambridge Park Drive 3rd Floor - Cambridge, MA 02140 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);
   }
}