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

# Module

**Code:**[ _guthscp.module.meta_](https://github.com/Guthen/guthscpbase/blob/master/lua/guthscp/keter/module/meta.lua)

**Realm:** <img src="https://975014697-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZXSL4k4DnVhJ9UWciTTm%2Fuploads%2Fw23hGHIIzuzjREdszv2f%2Frealm%20shared.png?alt=media" alt="" data-size="line"> Shared

***

## Description

{% hint style="info" %}
For more information about **creating a module**, read this [tutorial](../developpers/creating-a-module).
{% endhint %}

{% hint style="warning" %}
TODO
{% endhint %}

***

## Properties

**`string`** `name`

&#x20;   Name of the module, used in the menu

***

**`string`** `author`

&#x20;   Author of the module, used in the menu

***

**`string`** `version`

&#x20;   [Semantic Version](https://semver.org) 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"`

&#x20;   Description of the module, used in the menu. Multilines string are supported.

***

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

&#x20;   Icon path of the module, used in the menu. The pointed material must be a 16x16px image, use a [Silkicon](http://www.famfamfam.com/lab/icons/silk/preview.php) or make your own.

***

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

&#x20;   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.

&#x20;   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.

&#x20;   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.

&#x20;   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.

&#x20;   For example:

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

***

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

&#x20;   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`).

&#x20;   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`).

&#x20;   For example, considering this module's file structure:

```lua
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
```

&#x20;   The following `requires`..:

```lua
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
},
```

&#x20;   ..will load the following files to their respecting realm-side:

```lua
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`

&#x20;   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`

&#x20;   Identifier of the module, used for registering in the configuration and the module systems.

{% hint style="warning" %}
This variable shoult NOT be edited manually, this is automatically set to your module folder's name.
{% endhint %}

***

**`(internal)`** **`table`** `_`

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

**`bool`** `is_initialized=false`

&#x20;   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`

&#x20;   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.

&#x20;   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"`

&#x20;   Version retrieved by the online version checking. Set at the same time as `MODULE.version_check`'s final result.

**`table`** `warnings={}`

&#x20;   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

{% hint style="warning" %}
TODO
{% endhint %}
