Export Functions

Guide to export functions from your plugin to be used by other language modules within Plugify.

In the Plugify ecosystem, Lua plugins can export functions to make them accessible to other plugins. This guide explains how to define and export functions in Lua and provides examples to help you integrate your plugins seamlessly.

Basic Type Mapping

The following table lists how types are exposed to the Lua API:

C++ Type	Lua Type	Plugify Alias	Ref Support ?
void	nil	void	❌
bool	boolean	bool	✅
char	string	char8	✅
char16_t	string	char16	✅
int8_t	integer	int8	✅
int16_t	integer	int16	✅
int32_t	integer	int32	✅
int64_t	integer	int64	✅
uint8_t	integer	uint8	✅
uint16_t	integer	uint16	✅
uint32_t	integer	uint32	✅
uint64_t	integer	uint64	✅
uintptr_t	integer	ptr64	✅
uintptr_t	integer	ptr32	✅
float	number	float	✅
double	number	double	✅
void*	function	function	❌
plg::string	string	string	✅
plg::any	any	any	✅
plg::vector<bool>	table	bool[]	✅
plg::vector<char>	table	char8[]	✅
plg::vector<char16_t>	table	char16[]	✅
plg::vector<int8_t>	table	int8[]	✅
plg::vector<int16_t>	table	int16[]	✅
plg::vector<int32_t>	table	int32[]	✅
plg::vector<int64_t>	table	int64[]	✅
plg::vector<uint8_t>	table	uint8[]	✅
plg::vector<uint16_t>	table	uint16[]	✅
plg::vector<uint32_t>	table	uint32[]	✅
plg::vector<uint64_t>	table	uint64[]	✅
plg::vector<uintptr_t>	table	ptr64[]	✅
plg::vector<uintptr_t>	table	ptr32[]	✅
plg::vector<float>	table	float[]	✅
plg::vector<double>	table	double[]	✅
plg::vector<plg::string>	table	string[]	✅
plg::vector<plg::any>	table	any[]	✅
plg::vector<plg::vec2>	table	vec2[]	✅
plg::vector<plg::vec3>	table	vec3[]	✅
plg::vector<plg::vec4>	table	vec4[]	✅
plg::vector<plg::mat4x4>	table	mat4x4[]	✅
plg::vec2	Vector2	vec2	✅
plg::vec3	Vector3	vec3	✅
plg::vec4	Vector4	vec4	✅
plg::mat4x4	Matrix4x4	mat4x4	✅

Exporting Functions in Lua

Lua functions can be exported by defining them in your plugin and referencing them in the .pplugin manifest. Plugify’s Lua Language Module will handle the necessary type conversions.

Basic Example

Here’s a simple example of exporting a function in a Lua plugin:

Function Definition

plugin.lua

function addNumbers_exported(a, b)
    -- Adds two integers
    return a + b
end

Plugin Manifest

To export the function, describe it in the plugin manifest under the methods section:

plugin_name.pplugin

{
  "name": "ExampleLuaPlugin",
  "version": "1.0.0",
  "methods": [
    {
      "name": "addNumbers",
      "funcName": "addNumbers_exported",
      "paramTypes": [
        {
          "type": "int32",
          "name": "a"
        },
        {
          "type": "int32",
          "name": "b"
        }
      ],
      "retType": {
        "type": "int32"
     }
   }
 ]
}

Advanced Example: Exporting Complex Functions

Here’s an example of exporting a function with complex parameter and return types:

Function Definition

plugin.lua

function processData_exported(data, prefix)
    local result = {}
    for i = 1, #data do
        result[i] = prefix .. tostring(data[i])
    end
    return result
end

Plugin Manifest

plugin_name.pplugin

{
  "name": "ExampleLuaPlugin",
  "version": "1.0.0",
  "methods": [
    {
      "name": "processData",
      "funcName": "processData_exported",
      "paramTypes": [
        {
          "type": "float[]",
          "name": "data"
        },
        {
          "type": "string",
          "name": "prefix"
        }
      ],
      "retType": {
        "type": "string[]"
      }
    }
  ]
}

Exporting Functions with References

Plugify supports reference parameters in dynamically-typed languages like Lua, but they work differently than in statically-typed languages. In Lua, you cannot directly modify parameters passed by reference. Instead, you must return a tuple where:

First element: The function's return value (use nil if the function returns void)
Remaining elements: Modified values for all reference parameters, in order

Function Definition with Reference Parameters

plugin.lua

function incrementValue_exported(value)
    -- Increment the value
    -- Return: (return_value, modified_value)
    return nil, value + 1
end

function calculate_exported(a, b, sum, product)
    -- Calculate sum and product
    -- Return: (return_value, sum, product)
    local calculatedSum = a + b
    local calculatedProduct = a * b
    return nil, calculatedSum, calculatedProduct
end

function processAndCount_exported(data, prefix)
    -- Process data and return both result and count
    -- Return: (result, count) - both are actual returns, not refs
    local result = {}
    for i = 1, #data do
        result[i] = prefix .. tostring(data[i])
    end
    local count = #data
    return result, count
end

Plugin Manifest with Reference Parameters

In the manifest, mark parameters that should be treated as references using "ref": true:

plugin_name.pplugin

{
  "name": "ExampleLuaPlugin",
  "version": "1.0.0",
  "methods": [
    {
      "name": "incrementValue",
      "funcName": "incrementValue_exported",
      "paramTypes": [
        {
          "type": "int32",
          "name": "value",
          "ref": true
        }
      ],
      "retType": {
        "type": "void"
      }
    },
    {
      "name": "calculate",
      "funcName": "calculate_exported",
      "paramTypes": [
        {
          "type": "int32",
          "name": "a"
        },
        {
          "type": "int32",
          "name": "b"
        },
        {
          "type": "int32",
          "name": "sum",
          "ref": true
        },
        {
          "type": "int32",
          "name": "product",
          "ref": true
        }
      ],
      "retType": {
        "type": "void"
      }
    },
    {
      "name": "processAndCount",
      "funcName": "processAndCount_exported",
      "paramTypes": [
        {
          "type": "float[]",
          "name": "data"
        },
        {
          "type": "string",
          "name": "prefix"
        },
        {
          "type": "int32",
          "name": "count",
          "ref": true
        }
      ],
      "retType": {
        "type": "string[]"
      }
    }
  ]
}

How It Works

Return Order: The first return value is the function's actual return value. Subsequent values correspond to reference parameters in order.
Void Functions: If the function returns void, the first element of the tuple must be nil.
Mixed Returns: If a function has both a return value and reference parameters, the return value comes first, followed by all reference parameters.

Reference Parameter Support

Reference parameters work with most Plugify types as shown in the "Ref Support" column of the type mapping table. The following types do not support references:

void/nil (cannot be passed by reference)
function (callback types)

All other types including primitives, strings, and tables support reference parameters via the tuple return pattern.

Handling Callbacks

Plugify allows you to export functions that accept callbacks as parameters. Here’s an example:

Function Definition

plugin.lua

function executeWithCallback_exported(value, inputStr, callback)
    local result = callback(value, inputStr)
    print("Callback result:", result)
end

Plugin Manifest

plugin_name.pplugin

{
  "name": "ExampleLuaPlugin",
  "version": "1.0.0",
  "methods": [
    {
      "name": "executeWithCallback",
      "funcName": "executeWithCallback_exported",
      "paramTypes": [
        {
          "type": "int32",
          "name": "value"
        },
        {
          "type": "string",
          "name": "inputStr"
        },
        {
          "type": "function",
          "name": "callback",
          "prototype": {
            "name": "exampleCallback",
            "funcName": "exampleCallback_exported",
            "paramTypes": [
              {
                "type": "int32",
                "name": "value"
              },
              {
                "type": "string",
                "name": "inputStr"
              }
            ],
            "retType": {
              "type": "string"
            }
          }
        }
      ],
      "retType": {
        "type": "void"
      }
    }
  ]
}

Best Practices

Define Functions Clearly: Ensure your functions are well-documented and easy to understand.
Follow Type Conventions: Adhere to Plugify's type conventions for parameters and return values.
Test Thoroughly: Test your exported functions to ensure they work as expected when called by other plugins.
Update the Manifest: Always describe exported functions in the plugin manifest under the methods section.

Conclusion

Exporting functions in Lua plugins is clean and flexible. Just define your functions, register them in your manifest, and they become accessible to other modules. For more advanced scenarios, including passing callbacks, refer to the examples in this guide.

Edit this page on GitHub

First Plugin

Learn how to create your first plugin with the language module, including basic syntax and setup.

Import Functions

Learn how to import functions from other plugins written in different languages and use them in your own.