Plugin Packages

When writing a plugin, you must provide some extra information in the pawn.json to help sampctl find your plugin binaries. Before you do this, it's important that your GitHub release filenames follow a standardised naming convention, if this is not the case you should go and edit the filenames.

resources

This is a special field in pawn.json for plugin maintainers only. This allows a plugin developer to declare that their library also contains some additional files necessary for running the built .amx that uses their .inc file.

The resources field is an array of "Resource" objects, each Resource matches a single file from a GitHub Release - these are known by GitHub as "Assets".

For example, here's a resources array that contains two Resource objects which correspond to two Assets, one for Windows and one for Linux:

{
  "resources": [
    {
      // a regular expression to match the filename of a GitHub release
      // in this example, our windows releases use .zip files and Linux .tar.gz
      // the releases also contain the version number in the name so we use a
      // .* selector to match any version name.
      "name": "awesome-plugin-(.*)\\.zip",

      // target platform, either "windows" or "linux"
      "platform": "windows",

      // target server version, either "0.3.7" or "0.3DL" (default is "0.3.7" when not set)
      "version": "0.3.7",

      // a boolean indicating whether or not the file is an archive or just the binary itself
      "archive": true,

      // The following fields only apply if the resource is an archive

      // list of directory paths inside the archive that contain .inc files
      // in this example there is a directory named "pawno" and in that,
      // "include" which is common practice for plugin releases.
      // Notice how we add the directory, not the individual include file.
      "includes": ["pawno/include"],

      // the actual plugin filename - in this example, inside the archive is a
      // directory named "plugins" which contains our .dll file
      "plugins": ["plugins/awesome-plugin.dll"],

      // some plugins require additional libraries (MySQL is a good example)
      // so this field allows you to specify any additional files where the key
      // is the path inside the archive and the value is the target path for
      // when it gets extracted to the server directory. Most of the time,
      // additional shared objects/DLLs should be in the same directory as the
      // SA:MP server executable so there is no need to specify any additional
      // directories in the value string.
      "files": {
        "deps/libcurl.dll": "libcurl.dll"
      }
    },
    {
      // notice how this Resource object has a different "name" field. Some
      // plugins may ship binaries for both platforms in the same file so in
      // that case you'd simply specify the same filename in two separate
      // Resource objects. See Streamer plugin for an example of this.
      "name": "awesome-plugin-(.*)\\.tar\\.gz",
      "platform": "linux",
      "archive": true,
      "includes": ["pawno/include"],
      "plugins": ["plugins/awesome-plugin.so"],
      "files": {
        "deps/libcurl.so": "libcurl.so"
      }
    }
  ]
}

name

This is an important field, it must be a valid regular expression and it must match at least one filename from any GitHub release. This is used to find the correct file to download for the given platform. Some plugins (such as the streamer) release all their binaries in a single .zip so it's fine if two resource fields point to the same file. Please see the Streamer Plugin Package Definition for an example.

platform

This is simply the platform that this resource is for. Most plugins should have exactly two resource objects, one for linux and one for windows.

archive

If false means that the resource just points to a raw .so or .dll file and it can simply be automatically downloaded to the plugins directory without any hassle. If it's true, the next few fields are necessary to tell sampctl where in the archive the plugin files and any other important things exist.

includes

Used by sampctl package ensure for plugins that release their .inc files inside the release archives instead of on the repository itself. If your .inc file is simply kept in the repository, this field is not necessary.

plugins

This is a list of files inside the archive that are plugin files. Most plugins should only list one file, and depending on the platform this file should be an .so for linux and a .dll for windows.

files

This is any other necessary files. This is rarely ever needed. An example of this is the MySQL plugin, it requires the log-core dynamic library in order to run. The structure of this field is simply a string-to-string map where the left side are paths inside the archive and the right side are paths outside relative to the server root:

{
  "files": {
    "log-core.so": "log-core.so"
  }
}

Here, the log-core.so file is simply kept in the root of the archive, and it's target location is the root of the server runtime directory.

runtime

You need to declare that plugin as a runtime dependency and the path mirrors the user/repo fields. This tells sampctl that this particular package is a plugin itself. Yes, it's weird to think that this means the package depends on itself but this is just how it works!

{
  "user": "Southclaws",
  "repo": "awesome-samp-plugin",
  "entry": "test.pwn",
  "output": "test.amx",
  "dependencies": ["sampctl/samp-stdlib"],
  "runtime": {
    "plugins": ["Southclaws/awesome-samp-plugin"]
  }
}

This means that any package that depends on this one will know to automatically download the plugin when it's run.