classDocs / Addon

Addon

classsharedsource

Object → Addon

The Garry's Mod addon (.gma) archive.

Parses and builds the same format as gmad, legacy LZMA compressed addons are decompressed on parse.

lua

local addon = Addon()
addon.title = "My Addon"
addon.type = "tool"
addon.tags = { "fun", "build" }
addon:addFile( "lua/autorun/test.lua", "print( 'hello' )" )

local data = addon:compile()
print( Addon( data ):readFile( "lua/autorun/test.lua" ) ) -- print( 'hello' )

Constructor

Addon(data: string?, ratio: number?): Addon

Fields

Name	Type	Description
`format_version`	`integer`	The version of the `.gma` format, `3` by default.
`steamid`	`steam.Identifier`	The Steam ID of the author, all zero bytes by default (`gmad` doesn't set it).
`timestamp`	`integer`	The Unix timestamp of the creation in seconds.
`required_content`	`string[]`	The content required by the addon, unused by the game.
`title`	`string`	The title of the addon.
`description`	`string`	The description of the addon.
`type`	`string`	The type of the addon, one of `AddonClass.Types`.
`tags`	`string[]`	The tags of the addon, from `1` to `3` of `AddonClass.Tags`.
`author`	`string`	The author of the addon, unused by the game.
`version`	`integer`	The version of the addon, unused by the game.
`files`	`Addon.File[]`	The files of the addon.
`file_count`	`integer`	The number of files.
`size`	`integer`	The size of the addon data in bytes without the trailing checksum, `0` until parsed or compiled.
`checksum`	`integer`	The CRC-32 checksum of the addon data, `0` until parsed or compiled.
`legacy`	`boolean`	`true` if the parsed addon was LZMA compressed.
`data`	`string \| nil`	The parsed addon data, the content of not yet read files.
`file_indexes`	`table<string, integer>`	The indexes of files in `files` by their paths.
`Signature`	`integer`	`GMAD` as little endian uint32.
`Version`	`integer`	The latest supported format version.

Static functions

`isAllowedPath`	Checks if the file path is allowed by the gmad whitelist.
`isValidTag`	Checks if the tag is allowed by gmad.
`isValidType`	Checks if the type is allowed by gmad.

#Addon.isAllowedPath

sharednodiscardsource

function Addon.isAllowedPath(file_path: string): boolean

Checks if the file path is allowed by the gmad whitelist.

Parameters

Name	Type	Description
`file_path`	`string`	The path of the file inside of the addon, e.g. `lua/autorun/test.lua`.

Returns

Type	Name	Description
`boolean`	`is_allowed`	`true` if the path is allowed.

#Addon.isValidTag

sharednodiscardsource

function Addon.isValidTag(tag_name: string): boolean

Checks if the tag is allowed by gmad.

Parameters

Name	Type	Description
`tag_name`	`string`	The addon tag, e.g. `fun`.

Returns

Type	Name	Description
`boolean`	`is_valid`	`true` if the tag is allowed.

#Addon.isValidType

sharednodiscardsource

function Addon.isValidType(type_name: string): boolean

Checks if the type is allowed by gmad.

Parameters

Name	Type	Description
`type_name`	`string`	The addon type, e.g. `tool`.

Returns

Type	Name	Description
`boolean`	`is_valid`	`true` if the type is allowed.

Methods

`addFile`	Adds the file to the addon, replaces the existing file with the same path.
`compile`	Builds the .gma data of the addon, same as gmad create.
`getFile`	Returns the file of the addon.
`isAllowed`	Checks the addon against the gmad rules: an allowed type, 1 - 3 unique allowed tags and whitelisted file paths.
`mount`	Compiles the addon into a temporary .gma in /garrysmod/data/dreamwork/tmp/ and mounts it into the game.
`parse`	Replaces the addon with the parsed .gma data.
`readFile`	Returns the content of the file of the addon.
`removeFile`	Removes the file from the addon.
`verify`	Checks the CRC-32 checksums of the parsed addon data and all files.

#Addon:addFile

sharedsource

function Addon:addFile(file_path: string, content: string): Addon.File

Adds the file to the addon, replaces the existing file with the same path.

The path is lowercased, same as gmad does.

Parameters

Name	Type	Description
`file_path`	`string`	The path of the file inside of the addon, e.g. `lua/autorun/test.lua`.
`content`	`string`	The file content.

Returns

Type	Name	Description
`Addon.File`	`file`	The added file.

#Addon:compile

sharednodiscardsource

function Addon:compile(): string

Builds the .gma data of the addon, same as gmad create.

Updates size and checksum of the addon.

Doesn't check type, tags and file paths, use validate for that.

Returns

Type	Name	Description
`string`	`data`	The `.gma` data.

#Addon:getFile

sharednodiscardsource

function Addon:getFile(file_path: string): Addon.File | nil

Returns the file of the addon.

Parameters

Name	Type	Description
`file_path`	`string`	The path of the file inside of the addon.

Returns

Type	Name	Description
`Addon.File \| nil`	`file`	The file, `nil` if there is no such file.

#Addon:isAllowed

sharednodiscardsource

function Addon:isAllowed(): boolean, string | nil

Checks the addon against the gmad rules: an allowed type, 1 - 3 unique allowed tags and whitelisted file paths.

Returns

Type	Name	Description
`boolean`	`is_valid`	`true` if the addon follows the rules.
`string \| nil`	`reason`	The reason why the addon is invalid.

#Addon:mount

sharedasyncsource

async function Addon:mount(): boolean, string[]

Compiles the addon into a temporary .gma in /garrysmod/data/dreamwork/tmp/ and mounts it into the game.

The file is written asynchronously when called from a coroutine. Mounted addons cannot be unmounted, so the file stays until the game is closed.

Returns

Type	Name	Description
`boolean`	`success`	`true` if the addon was mounted.
`string[]`	`files`	If successful, a list of files that have been mounted.

#Addon:parse

sharedasyncsource

async function Addon:parse(data: string, ratio?: number)

Replaces the addon with the parsed .gma data.

Legacy LZMA compressed addons are decompressed first, on a separate thread when HolyLib is installed and the call is made from a coroutine.

File contents are not copied, they are read from the data on demand by readFile.

ratio limits how much a legacy addon may expand, see lzma.decompress; pass a value like 0.99 for untrusted data, since a few bytes of crafted lzma data can claim up to 4 GiB of output.

Parameters

Name	Type	Description
`data`	`string`	The `.gma` data.
`ratio`optional	`number`	The maximum allowed compression ratio of legacy addons, no limit by default.

#Addon:readFile

sharednodiscardsource

function Addon:readFile(file_path: string): string | nil

Returns the content of the file of the addon.

Parameters

Name	Type	Description
`file_path`	`string`	The path of the file inside of the addon.

Returns

Type	Name	Description
`string \| nil`	`content`	The file content, `nil` if there is no such file.

#Addon:removeFile

sharedsource

function Addon:removeFile(file_path: string): boolean

Removes the file from the addon.

Parameters

Name	Type	Description
`file_path`	`string`	The path of the file inside of the addon.

Returns

Type	Name	Description
`boolean`	`removed`	`true` if the file was removed, `false` if there is no such file.

#Addon:verify

sharednodiscardsource

function Addon:verify(): boolean, string | nil

Checks the CRC-32 checksums of the parsed addon data and all files.

Zero checksums are skipped, same as gmad.

Returns

Type	Name	Description
`boolean`	`is_valid`	`true` if all checksums match.
`string \| nil`	`file_path`	The path of the first damaged file, `nil` if the addon data itself is damaged.