[[HLF]Southclaw]

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

sampctl

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:





Problems?

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.

Quote:

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
  
• README.md: 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 helloworld.inc 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) {
    HelloWorld(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 код:

{
  "user": "Southclaws",
  "repo": "hello-world",
  "entry": "test.pwn",
  "output": "test.amx",
  "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 "helloworld.inc" // include your library

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

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
  changes
  
• run tests: this runs the package
  
• run tests watcher: this monitors the package and builds it whenever a file
  changes
  
  

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;
    HelloWorld(-1);
}

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.

Nope.

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

Conclusion

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!

[Freaksken]

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

Great tutorial btw.

[Revazix]

thanks for this

[OneDay]

It is very good explanation. Thankyou.

[Eoussama]

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.