Package and publish

Required archive layout

Correct:

example.splug
├─ manifest.json
├─ main.lua
├─ modules/
└─ assets/

Incorrect:

example.splug
└─ example/
   ├─ manifest.json
   └─ main.lua

Create the package with any ZIP tool:

1. Open the plugin project directory.
2. Select manifest.json, the Lua entry file, and the plugin's other files and directories. Do not select the outer project directory.
3. Create a standard ZIP archive without encryption.
4. Open the archive and confirm that manifest.json is directly at its root.
5. Confirm that nested entry names use /, such as modules/settings.lua.
6. Rename example.zip to example.splug.
7. Import the resulting file into the app and test a clean installation.

Windows paths

Do not use a packaging method that stores nested ZIP entries with \. Backslashes are rejected on every platform. Open the finished archive with a ZIP viewer and inspect at least one nested entry before publishing.

Using Plugin Tools

The Plugin Tools repository provides a samp-plugin CLI to automate validation and packaging. This is the recommended way to ensure your package meets all client requirements.

# Validate your plugin source directory
samp-plugin validate path/to/plugin

# Pack into a .splug file
samp-plugin pack path/to/plugin

# Validate an existing .splug package
samp-plugin validate my-plugin-1.0.0.splug

The repository also includes example plugins that demonstrate the full API surface.

Release checksum

Publish the SHA-256 of the exact .splug file:

Windows PowerShell

Get-FileHash .\example.splug -Algorithm SHA256

Linux

sha256sum example.splug

macOS

shasum -a 256 example.splug

Versioning

• Increase version for every content change.
• Never publish different bytes under the same ID and version.
• Use apiVersion to state compatibility.
• Document permission additions because users must approve them again.
• Keep migrations backward compatible with existing private storage.

Release checklist

1. Validate the manifest and package root.
2. Test clean install, update, disable, unload, and uninstall.
3. Test both supported ABIs.
4. Test callback errors, reconnect, and stale handles.
5. Confirm permissions match actual behavior.
6. Calculate and publish the exact package SHA-256.
7. Keep the previous stable version available for rollback.