SA-MP Forums

Go Back   SA-MP Forums > SA-MP Scripting and Plugins > Scripting Help > Tutorials

Thread Tools Display Modes
Old 16/03/2018, 04:45 PM   #1
[HLF]Southclaw's Avatar
Join Date: Apr 2009
Location: England
Posts: 4,987
Reputation: 1558
Default sampctl hello world - learn the sampctl workflow in 10 minutes

sampctl hello world

A simple sampctl tutorial for building a “hello world” library using the recommended sampctl workflow and tools.

The goal of this tutorial is to make you familiar with the workflow of building libraries with sampctl. This tutorial uses Visual Studio Code as an editor, this will work with any editor (even Pawno, if you’re oldschool) but VS Code is my personal favourite and my recommendation - I used Sublime for years and tried Atom and I prefer VS Code.

This tutorial also assumes you’re using Windows - as far as I know, most users are on Windows but the tools (vscode, sampctl) work on all platforms.

Getting Started


Obviously you need sampctl installed - this is a super simple process and is described in the official thread or the readme.

Visual Studio Code (“vscode”)

Get vscode installed - if you’re a Sublime user you can follow along in the terminal but vscode works really well with sampctl and you’ll be impressed so give it a try - you can always uninstall it after if you don’t like it!

A lot of people think this is Visual Studio - the huge C++/C# development environment - this is incorrect, VS Code is like the little brother of Visual Studio and is much more light-weight with faster start-up time and a simpler interface.

Pawn Tools for vscode

This is an extension pack I built with help from the community for vscode, it adds Pawn language syntax highlighting and some additional tools that integrate with sampctl.

Installing it is as simple as:


If you run into issues, just @ me on Discord or ask in this thread!

Create a Folder for your Project

First you need to create a directory dedicated to your package. This is standard in many languages. It’s common for Pawn includes to only exist in a single .inc so it might be tempting to keep all your .inc files in a single folder - don’t do this! You’ll get lost and disorganised and Pawn Packages (discussed below) aren’t composed of just a single .inc file but a few additional files so it’s necessary to bundle all of these together into a folder.

Once you’ve done that, open the folder in vscode (“File” > “Open Folder…”). This might be a new concept to you if you’re coming from Pawno or other simple editors. vscode can open individual files however when working on a project where you have an entire folder dedicated to that project, you can open the entire folder in a single instance of vscode. This makes jumping between files really easy and with the integrated terminal it becomes trivial to run commands.

Create a Package

So now you have all the tools installed and set up a folder you can create a Pawn Package.

Pawn Packages are described in detail here - essentially, they are just includes but with a bit of extra information to help sampctl understand how to get them and build them - to help sampctl help you!

So how do we do this? Open up the vscode integrated terminal with CTRL+` or by clicking “View” > “Integrated Terminal” on the menu at the top.

This will open your default shell at the bottom of the vscode window - on Windows this is either CMD or PowerShell, doesn’t really matter which you use.


side note: if you’re not using vscode, you can achieve the same results below
by just using CMD or PowerShell directly. Shift+Right Click inside your
project’s folder in the File Explorer window and clicking “Open Command Prompt
here” or “Open PowerShell here”.
Once you’ve got a terminal open, simply enter the following command:

sampctl package init
And follow the on-screen menus to create your package, for example:

This will generate the following files:
  • .gitattributes: tells GitHub to mark your repo language as “Pawn”
  • .gitignore: tells git to ignore certain files
  • .vscode: contains some vscode-specific settings
  • documentation template for your package - edit this later
  • dependencies: this folder contains the includes your package requires
  • pawn.json: this file is very special!

Feel free to familiarise yourself with these files. They are all necessary to help certain tools work well. For example, the .git... files are for Git and GitHub, .vscode helps your editor provide useful development features and pawn.json is to help sampctl configure your package and speed up your workflow.

Write Some Code!

Okay that’s all well and good but we still haven’t written a single line of code yet! We’ll do that now.

This “Hello World” package isn’t a Pawn tutorial, so the code itself will be very simple.

We’re going to write and test a library that simply sends a Hello World message to the server console and to players that join the server.

Create a file called with the following contents:


#include <a_samp>

HelloWorld(playerid) {
    if(IsPlayerConnected(playerid)) {
        printf("Saying hello to %!d(MISSING)", playerid);
        SendClientMessage(playerid, 0xFF3200FF, "Hello World!");
    } else {
        print("Hello World sampctl!");

public OnPlayerConnect(playerid) {
    return 1;

If the code isn’t highlighted, click the syntax button at the bottom right of the vscode window, it probably says “Plain Text” so click it and select “Pawn” from the drop-down menu.

Build The Code

Now we have some source code but there’s something missing…

You don’t typically compile .inc files - they are meant for including. What we need is an entry file to compile from.

What makes an entry file an entry file? Two properties:
  • It must have a main() function
  • It must be listed in the pawn.json file in the entry field

Open up your package’s pawn.json file, you should see something like this:

PHP Code:
"dependencies": ["sampctl/samp-stdlib"]

As you can see, the sampctl package init process pre-populated the entry and output fields. These fields are simple, entry is the file passed to the compiler and output is the name of the resulting .amx file.

Since test.pwn is already there (this is the default) go ahead and create a file named test.pwn in your workspace by clicking the “New File” button:

And in this file, add the following code:


#include "" // include your library

main() {
    // pass an invalid player ID so we get "Hello World sampctl!" in the console

Now, in the terminal, run sampctl package build - this will magically compile the package and output a test.amx file to your workspace.

Build The Code - But In a Cooler Way

Okay so you built some code, nice, but using the terminal isn’t really taking advantage of the neat features of vscode and the Pawn Tools extension.

Without getting into the details of the vscode tasks.json file format and how powerful it is, I’ll quickly go over what tasks are.

Inside the .vscode directory, you’ll find a file named tasks.json, this file declares 4 tasks:
  • build only: this just builds the package by running
    sampctl package build - same as you did in the section above
  • build watcher: this monitors the package and builds it whenever a file
  • run tests: this runs the package
  • run tests watcher: this monitors the package and builds it whenever a file

The watcher tasks are really useful and the run tasks we’ll get into in the next section.

So to really show the power of this, you need to introduce bad code to trigger an error, in the main() function, add an unused variable:


main() {
    new unused;

Then hit CTRL+Shift+B to run the build task, your editor will highlight the line and also display it in the “Problems” panel at the bottom of the vscode window.

Build The Code - But In an Even Cooler Way!

So you can build code with keyboard shortcuts, big woop, Pawno can do this…

The real magic here is the build watcher task. To run this, hit CTRL+Shift+P to open the command palette.

This is similar to the terminal but it’s a special area to write commands to vscode itself, it allows you to control the editor with just your keyboard, which can seriously speed up your workflow.

In the command palette, type Run task, hit enter or click it and then hit build watcher:

Now remove the new unused; you added earlier and save the file with CTRL+S - watch as sampctl will recompile your code and vscode will update the interface to remove the notification on the line with the warning.

You can leave the build watcher task running constantly and it will always be recompiling your code and updating the editor view so you can focus on what’s important: the code.

Run The Code

Okay that’s enough building, it’s time to actually run the code.

Now you may be thinking, this is Pawn, surely you’d need to get the samp-server.exe files, create a gamemodes folder, create a gamemode, set up server.cfg to load your gamemode, double click the samp-server.exe and observe the output.


Just type:

sampctl package run
And the package will just run, no need to worry about the rest, sampctl does all that for you.

Run The Code - But In a Cooler Way

So if you remember from when I listed the tasks in tasks.json there is a run tests and run tests watcher - these do exactly what you expect. The first simply runs sampctl package run and the second does what the build watcher does, but also runs the package.

This can be a very useful development tool, especially if you have two monitors because you can run vscode on one and GTA in another (in Windowed mode) and seamlessly write code, save it and jump in game as the server restarts with the new code.

Another use-case for the run tests watcher task is unit tests with y_testing, but that’s a topic for another day


Hopefully you found this useful. If you’re new to Pawn or just new to sampctl, I hope you found this useful and if you have any questions about this workflow, please drop a reply below and I’ll help you out!



[HLF]Southclaw is offline   Reply With Quote
Old 17/03/2018, 02:09 AM   #2
Freaksken's Avatar
Join Date: Mar 2009
Location: Belgium
Posts: 532
Reputation: 305
Default Re: sampctl hello world - learn the sampctl workflow in 10 minutes

Hmmm ok, might check this thing out now that I get what it does...

Great tutorial btw.
Always keep in mind that a lot of people are active on this forum in their spare time.
They are sacrificing time they could easily spend on things they would rather do, to help you instead.

[Include] FCNPC A.I. - [Tutorial] Speedometer - [WIP] Single-player-like co-op mission - [Other] List of all my work
Freaksken is offline   Reply With Quote
Old 17/03/2018, 04:13 PM   #3
Big Clucker
Revazix's Avatar
Join Date: Sep 2015
Posts: 59
Reputation: 12
Default Re: sampctl hello world - learn the sampctl workflow in 10 minutes

thanks for this
Revazix is offline   Reply With Quote
Old 19/03/2018, 07:26 PM   #4
Huge Clucker
Join Date: Sep 2015
Posts: 291
Reputation: 126
Default Re: sampctl hello world - learn the sampctl workflow in 10 minutes

It is very good explanation. Thankyou.
OneDay is offline   Reply With Quote
Old 14/05/2018, 11:51 PM   #5
Eoussama's Avatar
Join Date: Jul 2016
Location: Kingdom of Morocco // Tangier
Posts: 1,285
Reputation: 266
Default Re: sampctl hello world - learn the sampctl workflow in 10 minutes

Can't believe I'm this late to using it, I absolutely loved npm when first introduced to it, and I get the same feeling about this, It's been a while since I did anything related to pawn, but this is making me very excited to just type some quality pawn code, great tutorial.

|===[Web taxi]===|
List of my work

|===[Interesting topics]===|
Semantic Versioning
Eoussama is offline   Reply With Quote

Thread Tools
Display Modes

Posting Rules
You may not post new threads
You may not post replies
You may not post attachments
You may not edit your posts

BB code is On
Smilies are On
[IMG] code is On
HTML code is Off

Similar Threads
Thread Thread Starter Forum Replies Last Post
[Tool/Web/Other] sampctl: The Swiss Army Knife of SA:MP - vital tools for any server owner or library maintainer [HLF]Southclaw Tools and Files 40 12/09/2018 02:28 AM
Save World - Load World Avi Raj Scripting Help 0 07/11/2013 03:03 PM
How to make an automatic gate that closes after 4 minutes and 2 minutes after re justinkomnuga Help Archive 4 06/04/2010 12:47 PM
World Longest Song is 9 years, 174 days, 03 hours, 00 minutes and 08 sec long! KeyWay Everything and Nothing 13 24/06/2009 08:36 PM

All times are GMT. The time now is 12:30 PM.

Powered by vBulletin® Version 3.8.6
Copyright ©2000 - 2018, Jelsoft Enterprises Ltd.