Skip to content

Quickstart

Jump to bottom
Barnaby Keene edited this page Apr 22, 2022 · 3 revisions

There is a great tutorial written by Vince0789 here: https://vince0789.com/miscellaneous/setting-up-your-environment#github

Writing a Pawn Package is a simple job, there is a command to help you kick-start a new package or turn an existing project (gamemode, library or filterscript) into a package:

sampctl package init

This will ask you a few questions and generate a Package Definition File - this is either JSON or YAML depending on which you choose during the init process.

During this tutorial, it's a good idea to check your pawn.json/pawn.yaml file after each command so you can learn how each command affects the Package Definition File.

To learn more about Pawn Packages in general, visit the Packages page.

SA:MP Standard Library

During the init process, you will be asked the following question:

Add standard library dependency?

The "standard library" is a_samp.inc and friends, that is packaged with the Windows SA:MP server download.

When you hit Yes, this will add sampctl/samp-stdlib to your dependencies field and also download all the include files to the dependencies/ directory. Because the samp-stdlib package depends on the pawn-stdlib package, this will also be downloaded and included into your builds.

Note: the init command asks you if you want to add this dependency automatically.

Automatic Dependency Search

Also during the init process, you will be asked:

Scan for dependencies?

Which will search your Pawn source files in the current folder for #include <...> lines. A list of popular includes have been added to sampctl which will automatically add them as dependencies when you answer Yes to this question.

Find More Dependencies

If the scanner has missed a few includes then simply check through your source for all the #include <...> lines in your .inc script(s) and find the GitHub pages for all of those libraries and add their user/repo paths to your dependencies field.

You can search for packages on packages.sampctl.com.

So if your script contains these:

#include <YSI\y_hooks>
#include <YSI\y_iterate>
#include <md-sort>

Then you'd run these installation commands:

sampctl package install sampctl/samp-stdlib
sampctl package install pawn-lang/YSI-Includes
sampctl package install oscar-broman/md-sort

Wait! I depend on a project that's not on GitHub! What Do I Do?

If your code requires code that has not been released on GitHub - no need to worry!

Either:

If the maintainer is inactive or has left the SA:MP community, it's likely they don't mind their work being forked onto GitHub - but it's always polite to check first!

Note: There seems to be a GitHub page named SAMP-git that is hosting non-GitHub Pawn packages - you can ask the owner to add a repository here.

entry and output

During the sampctl package init process you will have been asked about entry and output. This is your execution entry point because we don't want to attempt to compile the library directly because, well, it's a library and doesn't/shouldn't contain a main() function.

A test.pwn (or whatever you choose to name it) is simply there to simulate a user including and using your library. This is a must for testing libraries before release and sampctl makes that process extremely simple!

You either want to:

  • Create unit tests inside this script to make sure all your functions do what they should do. y_testing is a good library for this.
  • Create basic tests (also known as "smoke tests") - this is where you simply set up a bunch of calls to your library functions, some prints and stuff, just to make sure everything is doing what it should. It's nice and quick to do these and if your library is not complex, this should be enough.
  • Create demo tests - if your library provides in-game functionality that players interact with, treat your test.pwn file as a fully fledged gamemode and fill it with classes, commands, vehicles, whatever you need to demonstrate or test your library.

For more information, please refer to the Testing Pawn Code page.

How do I Run Tests?

In the old days, if you wanted to write a library, you'd need to:

  • download or get a server installation
  • set the gamemode0 field in server.cfg
  • make a gamemode (or use an existing gamemode)
  • compile it (if you're using an existing gamemode, it could take a while and break your tests)
  • install all your plugins

Not any more!

Just run sampctl package run --forceBuild!

This does all the hard work for you and automatically sets up a server with your test.pwn (or whatever you named it) as the running gamemode. You can quickly connect to localhost:7777 and test your library without any of the hassle of setting up a full server.

This also allows you to set up quick demonstrations. No more bandicam free version YouTube videos! Just write in your library release forum topic:

To test out the code, just download the package and run sampctl package run --forceEnsure --forceBuild

--forceEnsure will automatically run sampctl package ensure so all the dependencies are ready for building and --forceBuild will build the script before running it.

That's it.

That's literally it.

No more "how to install: download the inc, copy the inc into your pawno/includes, do a bunch of stuff, make sure you have YSI installed, make sure you have this other library installed, make sure you're using this plugin in your server.cfg, oh if you're on linux don't forget the .so on the plugins line" pure simplicity.

Maintaining Your Package

Versioning

The dependencies field allows versions to be specified. For more information on this, please read the Dependencies page.

sampctl uses Git Tags - or GitHub Releases to specify versions of libraries. In order to tag your library at a specific version (similar to how Incognito does with the Streamer Plugin)

In order to create a tag, use the git command line:

git tag 1.0.0

Or use the GitHub releases feature to create a release (which also creates a tag).

Be sure to use semantic versioning!

Updating Dependencies

Remember, if you modify your script to either require a new library or you've removed an #include line then update your pawn.json/pawn.yaml file too - otherwise users of your library will either be downloading unnecessary packages or getting build errors where they are missing include files.

Clone this wiki locally