====== 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