User Tools

Site Tools



private_addon_developer_help

Information on how to turn your LUA module into a private addon

The terms module and addon are used synonymously throughout the document. The addon is basically a lua module turned private (closed source). If you want to distribute or sell your module through our addon store, it will have to be adjusted to work. This document contains basic information on what needs to be done.

When a module is converted into an addon the following things will happen:

  • all files inside the module will be put into a single file
  • the folder structure of the module will be kept the same
  • all .lua files must be loaded through the .def file.
  • all .lua files will be merged into a single lua file before they are loaded

Additions to the .def file

CreateFolders: If you want to create subfolders on the local hdd to write logfiles or export files from inside your module, you can define a list of subfolders (single level) inside the .def file. Those folders will be created inside your modules local folder. FOLDER NAMES ARE CASE SENSITIVE!

Example:

CreateFolders=log,settings,files

ExportFiles: If you have files inside your module that need to be accessible from the local hdd of the user, you can have them exported. Files will always be exported from the folder you put them in and into the same local folder inside the module folder. You need to use the CreateFolders option to create any local folders or the export will fail. Files will be overwritten when your module is loaded, so don't export files that the user should be able to edit. Files and folders can only contain alphanumerical letters. FOLDER NAMES ARE CASE SENSITIVE!

Example:

ExportFiles=files/PlayerAlert.wav

Important: The “Name” entry in the .def file will be used to create your modules local folder. So pick a name that identifies your module properly. The name defined in the module.def file will be the name that the module is published in the addon store. If you want to load a local file, the path can be build as follows:

      local path = GetStartupPath() .. [[\LuaMods\{modulename}\]]

Lua code changes

All lua files in your module will be merged into a single file in the order they appear in the .def file. This will change the scope of your file local variables. Anything decleared as local inside one of your files (on file level, not function level) will now be local to the single large file. This makes your module use its own scope, that is not global, but you can still access all file local variables like globals inside your modules code. If you want to keep your modules data private, define your modules main table as local (see example below).

For testing purposes and debugging you can either merge your lua files into one file or just use globals instead of local variables.

A new function has been added to provide you with functions to load files from inside your module. To get the functions to load and list files you need to call GetPrivateModuleFunctions() at load time of your module. It will return a table containing all functions avaialable to your module.

Important: DO NOT STORE THE PRIVATE MODULE FUNCTIONTABLE IN A GLOBAL VARIABLE UNLESS YOU WANT EVERYBODY TO BE ABLE TO LOAD FILES FROM INSIDE YOUR MODULE !

Currently there are two function:

ReadModuleFile(filedata):
	Loads a single file from inside your module. It expects a table containing the keys p,m,f
		p: the folder inside your module
		f: the filename of the file you want to load
		m: the module name (not used)
		It will load the file into a lua string that can be parsed or passed to loadstring to be executed

GetModuleFiles("data"):
	Get all files inside the "data" subfolder. The function returns a table containing table entries having the keys p,m and f, with p=folder,m=modulename,f=filename, for each file in the folder. A subfolder is NEEDED, you don't have access to the root of your addon folder.
	Entries from this table can be passed to the ReadModuleFile function to load those files. The modulename is not used, you can only load files inside your own module.
      
CheckUserAddonOwnership({UUID}):
              Checks if the user owns the addon with that uuid. returns true or false. Your own addon uuids are displayed on the developer addon update page.
	

Here is an example of how to declare a local module main table and use the private module functions to load a file from inside the module:

Define your modules main table as local to protect it from outside access:

local modexample = {} -- defined as local, not accessible outside the file
modexample.ModuleFunctions = GetPrivateModuleFunctions() -- since modexample is local, so is ModuleFunctions

Modified loading function for persisted lua tables:

function modexample.LoadPersistentTable(name)
	if (modexample.ModuleFunctions ~= nil and modexample.ModuleFunctions.ReadModuleFile ~= nil) then
		local fileInfo = { p = "data" , m = "MyModule" , f =  name }
		local fileString = modexample.ModuleFunctions.ReadModuleFile(fileInfo)
		if (fileString) then
			local fileFunction, errorMessage = loadstring(fileString)
			if (fileFunction) then
				jtb[name] = fileFunction()
			else
				jtb[name] = {}
			end
		end
	end
end

Load a lua table stored with the persistance function:

modexample.SGD = modexample.LoadPersistentTable("SecretGameData.lua")

Get all files inside the “data” subfolder of your module:

          local filelist = modexample.ModuleFunctions.GetModuleFiles("data");

Sharing Data between private Addons

The addon that shares data: To allow access of other addons to the shared data, add this line to the .def file of the addon which shares the data:

SharedAccess=2948FB2D-0228-11EB-A373-52540012300A,2D980E1F-4729-11EA-BD7E-52540012300A

Where '2948FB2D-0228-11EB-A373-52540012300A' and '2D980E1F-4729-11EA-BD7E-52540012300A' are two private addon uuids, which are then able to access the shared data.

Lua code of the sharing addon:

          local testtable = {}
          testtable.Text = "private text"
          function testtable.Function() 
              d("called shared function")
          end
          local modulefunctions = GetPrivateModuleFunctions()
          if (modulefunctions ~= nil ) then	
            if( modulefunctions.SetPrivateModuleTable ~= nil) then
          	        res = modulefunctions.SetPrivateModuleTable(testtable)
            end
          end
          
          

To access the shared data from the allowed addons:

          local modulefunctions = GetPrivateModuleFunctions()
          if (modulefunctions ~= nil) then
            if( modulefunctions.GetPrivateModuleTable ~= nil) then
            	testtable = modulefunctions.GetPrivateModuleTable("0E964E39-0228-11EB-A373-52540012300A")  -- This is the addon UUID of the addon which shares the data!
            end
            if (testtable ~= nil) then
            	d(testtable)
            	testtable.Function()
            else
            	d("failed to get shared table")
            end
          end
private_addon_developer_help.txt · Last modified: 2020/12/02 13:29 by fxfire