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:
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}\]]
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");
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