How to create a plugin?

Introduction

The Lua Plugin API allows you to extend Infinity's core functionality and create custom plugins. Whether running as independent scripts within the engine, or creating new services exposing Web endpoints

This tutorial describes how to write plugins using the updated plugin framework and best practices to speed up your development process.

Before you start

Check that the plugins folder is well configured, the default is that you use the path $INFINITYDIR/plugins/ but you can configure the folder however you want in the file called infinity.conf :

[plugins]
path = "plugins/" # default path to search for plugins
enable = true
lua.standard.libraries = ['package', "string", "base", "io", "os"]

Get a sample plugin

In this tutorial, we'll use a simple sample plugin designed to work with a new plugin framework, which simplifies plugin development. The plugin performs a simple task: once invoked by the engine it exposes a web interface /engine/status with the method of then obtaining a printout for the user if the engine is running successfully.

You can download engine_status.lua from here:

611B

engine_status.lua

Writing a plugin in Lua—basic steps

Create a single .lua file to start

To begin with, your plugin must consist of a single Lua file that serves as an entry point. This file should define the main logic and include the necessary imports and primary functions that will be executed when the plugin is run.

Create web gateway - For external communication

Currently Infinity v1 only supports web gateways using plugins, but we have endpoints that the engine uses in websocket, if you create a web gateway and don't put a response by default, Infinity understands that the gateway exists and returns (200 OK)

Web.new(_server, "/tutorial", function (req)
    return Response.new(100, "Continue the tutorial ...")
end, HTTPMethod.Get)

For more information about the response possibilities and methods supported by the gateway, go to section gateways.

Accessing objects exposed by the engine

All objects exposed by the engine, only each feature has 1 exposure, for example the running engine, you can access its methods and members through _engine

Web.new(_engine.server, "/engine/status", function (req)
    return Response.new(200, tostring(_engine.is_running))
end, HTTPMethod.Get)

Note that I pass _engine.server, which is used by the engine, to the Web instance as the first parameter. Then, I access the is_running member, which serves as an object _engine control.

You can access all the objects that the mechanism exposes, you can check in the section Class members and functions the objects and their methods and members.

We can use json to build a more polished response

we will use the Json class to create a json and return the engine status with its fields to our endpoint

local engine_json = Json:new()

local engine_fields = Json:new()
engine_fields:add("is_running", _engine.is_running)

local engine_server = Json:new()
engine_server:add("port", _engine.server.port)
engine_server:add("bindaddr", _engine.server.bindaddr)
engine_server:add("concurrency", _engine.server.concurrency)
engine_server:add("ssl_enable", _engine.server.ssl_enable)

engine_fields:add("server", engine_server)

engine_json:add("engine", engine_fields)

Web.new(_engine.server, "/engine/status", function (req)
    return Response.new(200, "application/json", engine_json:to_string())
end, HTTPMethod.Get)

Expected response when we hit the /engine/status endpoint :

{
  "engine": {
    "is_running": true,
    "server": {
      "port": 8081,
      "bindaddr": "0.0.0.0",
      "concurrency": 4,
      "ssl_enable": true
    }
  }
}

Lua Standard Libraries

We use a default state to load plugins. So, let's assume you want to use a standard Lua library—you need to load it before your plugin. To do this, you must modify the lua.standard.libraries configuration file, specifying the name of the standard Lua library. I recommend checking the Lua Standard Libraries section in the configuration file.

If the created plugin needs to manipulate tables, it is necessary to import table into lua.

lua.standard.libraries = ["base", "table"] — include the table for the lua state to load the table

local items = {}

json:add("engine", "infinity/pro")
json:add("score", 10)

table.insert(items, json) -- using 'table' for insert json in items

json:add("items", items)