Plugin¶

Overview¶

The plugin module allows users to access and query properties for the current plugin, as well as access plugin resources.

Enumerations¶

PluginPermissions¶

Contains all permissions a plugin may request.

Value	Description
httpAccess	Allows the use of HTTP-related functionality if provided. Makes use of base URLs specified in the plugin's manifest file.
chatAccess	Allows the use of Chat-related functionality if provided.
trackingAccess	Allows the use of Tracking ID-related functionality if provided.

urls¶

Table containing all URLs specified in the current plugin's metadata.

See HTTP for more information on using these values along with examples.

Example

plugin.json

    "urls": { "wiki" : "http://www.runescape.wiki" },

plugin.lua

    -- Accessed as follows
    Plugin.urls.wiki

resources¶

Table containing all custom resources stored under the current plugin's resources folder, using their filenames as table keys. See Plugin Resources for information on how to use these.

Info

Nested folders are represented as sub-tables, so for example resources/images/menu/background.png can be accessed as Plugin.resources.images.menu.background.

Methods¶

HasPermission¶

function Plugin.HasPermission(permission : PluginPermissions) -> Bool

Checks if the user has allowed the specified permission for the current plugin.

Info

Unless your plugin won't work at all without a specific permission, prefer marking permissions as optional in the manifest and using HasPermission to check whether or not to enable functionality that depends on that permission.

Parameter	Type	Description
permission	PluginPermissions	The permission to check.

Returns	Description
Bool	True if the specified permission has been given to this plugin, false otherwise.

Example

if Plugin.HasPermission(PluginPermissions.httpAccess) then
    -- Use functionality that require httpAccess
end

Plugin Resources¶

Custom resources provided by plugins can be used as a alternative for built-in ones in various methods, but also provide some additional functionality.

Resources are automatically loaded on demand, or can be loaded explicitly by plugins, which can be useful when dealing with larger resources, or to keep audio in memory to avoid any delays.

See here on information on how to access the resources provided by a plugin.

Info

Support for custom resources is currently limited to the following types and their associated formats:

Sprites (PluginResource -> PluginImageResource): Portable Network Graphics (.png)
Audio (PluginResource -> PluginAudioResource): Ogg Vorbis (.ogg)

Warning

Once loaded, a resource will remain loaded until either the plugin that owns it is unloaded and all references to it are freed, or until the user manually unloads it.

Warning

Image resources are limited to a maximum size of 1024x1024 pixels currently.

Enumerations¶

PluginResourceLoadResult¶

Value	Description
success	The resource has been loaded successfully.
errorFilesystem	Failed to read the resource from disk.
errorDecode	Failed to decode the resource, it may be using an unsupported format.
errorExceedsLimits	Failed to load the resource as it exceeds limits.
errorConstruction	Failed to construct this resource even though loading succeeded. This can occur when attempting to load a resource during shutdown for example.

Methods¶

Load¶

function PluginResource<T>:Load() -> PluginResourceLoadResult

Attempts to load this resource, making it ready for immediate use afterwards if successful.

Returns	Description
PluginResourceLoadResult	Indicates whether loading succeeded, or the error in case it failed.

Unload¶

function PluginResource<T>:Unload()

Attempts to unload this resource's data.

No data is actually freed until all references to it have been released, meaning that if it's being used for a sprite elsewhere, that sprite will remain valid until it is removed as well, even though the resource itself has been unloaded.

Properties¶

Name	Type	Description
path	String	(Read-only) The disk path to this resource.
loaded	Bool	(Read-only) Whether the resource's data is currently loaded and ready to use.
inUse	Bool	(Read-only) Whether or not the resource is being used anywhere currently.