Module

External add-on coupled to the base and having its own page or configuration

Code: guthscp.module.meta

Realm: Shared

---

Description

For more information about creating a module, read this tutorial.

TODO

---

Properties

string name

Name of the module, used in the menu

---

string author

Author of the module, used in the menu

---

string version

Semantic Version of the module, used for dependency and online version checking. Pre-Release labels are supported but Build Metadata are not.

---

(optional) string description="No description"

Description of the module, used in the menu. Multilines string are supported.

---

(optional) string icon="icon16/brick.png"

Icon path of the module, used in the menu. The pointed material must be a 16x16px image, use a Silkicon or make your own.

---

(optional) table[string, string] dependencies={}

A string/string dictionary declaring the required modules and their versions to check by the module system before initializing this module. The key must be the module's identifier and the value must be the minimum compatible version.

If a dependency is not found, this module WILL instantly fail to initialize and an error message will be visible in the console and the module's page.

If a dependency have a lower local version than the required version defined in this dictionary, this module WILL instantly fail to initialize and an error message will be visible in the console and the module's page. However, if the versions differ at the pre-release depth (i.e. having a -<tag> at the end of the version; e.g. dev in 1.0.0-dev) it WILL only log a warning message.

In order to ensure that a compatible version of guthscpbase is used for your module, you should always have the base module as a dependency.

For example:

dependencies = {
    base = "2.0.0",
    --  add more dependencies here..
},

---

(optional) table[string, guthscp.REALMS] requires={}

A string/guthscp.REALMS dictionary declaring the files and folders relative to your module's folder to load during the initialization phase. The key must be the relative path and the value must be the including realm (either guthscp.REALMS.SERVER, guthscp.REALMS.CLIENT or guthscp.REALMS.SHARED).

Requiring a folder will NOT require all its sub-folders recursively, you have to list all sub-folders manually or to do it yourself in the MODULE:init (see guthscp.require_folder).

For example, considering this module's file structure:

my_module/
├── client/         --  client files
│   ├── subdir/
│   │   └── not_loaded.lua  --  this file won't be loaded
│   ├── file1.lua
│   └── file2.lua
│   server/
│   ├── myfile.lua  --  server file
│   └── not_loaded.lua  --  I don't want this file to be loaded either
├── myfile.lua      --  shared file
└── main.lua        --  the entry point

The following requires..:

requires = {
    ["client/"] = guthscp.REALMS.CLIENT,            --  load all folder's files (not recursive!)
    ["server/myfile.lua"] = guthscp.REALMS.SERVER,  --  only load `server/myfile.lua`
    ["myfile.lua"] = guthscp.REALMS.SHARED,         --  works also on root's folder
},

..will load the following files to their respecting realm-side:

my_module/
├── client/         --  client-side
│   ├── file1.lua
│   └── file2.lua
│   server/         --  server-side
│   └── myfile.lua
└── myfile.lua      --  server & client sides (shared)

---

(optional) string version_url=nil

URL to a (preferably) raw body page where the online version will be retrieved. If your module is available on a public Github repository, you can put the raw URL of the main.lua file.

---

(internal) string id

Identifier of the module, used for registering in the configuration and the module systems.

This variable shoult NOT be edited manually, this is automatically set to your module folder's name.

---

(internal) table _

Internal table used by the module system to store states. You should not edit them.

bool is_initialized=false

Is the module fully initialized? Set to true after MODULE:init method has been called by the module system.

guthscp.VERSION_STATES version_check=guthscp.VERSION_STATES.NONE

Current state of the local version, set by the online version checking. If MODULE.version_url is equal to nil, the variable will never change and the following will not occur.

Set to guthscp.VERSION_STATES.PENDING during module initialization. During the hook GM:InitPostEntity, a timer will be created to retrieve online versions of all the modules which have MODULE.version_url set. When the remote version is retrieved, MODULE.version_check will be set to either guthscp.VERSION_STATES.UPDATE or guthscp.VERSION_STATES.OUTDATE depending on the comparison result between the local and the online versions.

string online_version="0.0.0"

Version retrieved by the online version checking. Set at the same time as MODULE.version_check's final result.

table warnings={}

List of registered warnings, useful to alert users of something wrong in the module's page menu. Used by methods MODULE:add_warning and MODULE:add_error, which you can use. The module system use it to alert from updates (using online version checking), different dependency's major version and usage of development versions.

---

Methods

TODO