Skip to content

Latest commit

 

History

History
214 lines (148 loc) · 6.96 KB

readme_begin.md

File metadata and controls

214 lines (148 loc) · 6.96 KB

sampctl

Build Status Go Report Card Ko-Fi FOSSA Status

sampctl-logo

The Swiss Army Knife of SA:MP - vital tools for any server owner or library maintainer.

sampctl is a command-line development tool for developing SA:MP Pawn scripts. It includes a package manager, a build tool and a configuration manager.

If that sentence meant nothing to you, don't worry! You'll probably find use in sampctl if you do anything related to the Pawn language. Below are some explanations of what the terms in bold above mean.

  • command-line development tool: Whether you're a seasoned developer or just a beginner, mastering the command-line on Windows and Unix systems is absolutely necessary to speed up your workflow, take advantage of tools (like this one) and just generally improve your knowledge of computing. If you've never opened Cmd, PowerShell (Windows) or Terminal (Mac) then read this guide.
  • Pawn scripts: This includes gamemodes, filterscripts and libraries (includes). sampctl introduces the concept of packages to the SA:MP and Pawn world to make everyone's life easier.
  • package manager: This allows you to easily use and share packages, no more downloading outdated .inc files from solidfiles...
  • build tool: Easily experiment with new versions of the compiler with a simpler setup and automatic download feature.
  • configuration manager: server.cfg files can get messy and unmanageable, sampctl can generate this file automatically from a much cleaner looking JSON or YAML equivalent.

For a quick-start guide, click this link!

Features

As mentioned above, sampctl is a command-line development tool so it has no graphical user interface. The videos below show sampctl being used with Visual Studio Code which is a light-weight text editor that works very well with sampctl to provide the perfect SA:MP/Pawn development environment.

Package Manager

Always have the libraries you need. Inspired by npm.

images/sampctl-package-ensure.gif

Build/Run Tool

Use on the command-line or integrate with any editor.

images/sampctl-package-build-vscode.gif

Easily write and run tests for libraries or quickly run arbitrary code. Utilise the power of Docker to run on any platform!

images/sampctl-package-run-container.gif

Developer Tools

Quickly bootstrap new packages.

images/sampctl-package-init.gif

SA:MP Server Configuration - no more server.cfg

Manage your server settings in JSON or YAML format

images/sampctl-server-init.gif

Automatic Server Restart - no more dodgy bash scripts

Run the server from sampctl and let it worry about restarting in case of crashes.

images/sampctl-server-run.gif

Automatic Server and Plugin Installer

Automatically download Windows/Linux server binaries and plugins when and where you need them.

images/sampctl-server-ensure.gif

Installation

Installation is simple and fast on all platforms so why not give sampctl a try?

Usage

For a list of commands, click here.

Or visit the Wiki site for documentation on each feature..

Overview

sampctl is designed for both development of gamemodes/libraries and management of live servers.

Below is a quick overview of the best features that will help you develop faster.

Package Management and Build Tool

If you've used platforms like NodeJS, Python, Go, Ruby, etc you know how useful tools like npm, pip, gem are.

It's about time Pawn had the same tool.

sampctl provides a simple and intuitive way to declare what includes your project needs. After that you simply let sampctl take care of the downloading and building.

If you release scripts, you know it's awkward to test even simple code. You need to set up a server, compile the include into a gamemode, configure the server and run it.

Forget all that. Just make a pawn.json/pawn.yaml in your project directory with sampctl package init and use sampctl package install to get the includes you need:

{
  "entry": "test.pwn",
  "output": "test.amx",
  "dependencies": ["pawn-lang/samp-stdlib", "Southclaws/formatex"]
}

Write your quick test code:

#include <a_samp>
#include <formatex>

main() {
    new str[128];
    formatex(str, sizeof str, "My favourite vehicle is: '%v'!", 400); // should print "Landstalker"
    print(str);
}

Build with sampctl package build and run it with sampctl package run!

sampctl package run

Server Plugins
--------------
 Loaded 0 plugins.

Started server on port: 7777, with maxplayers: 50 lanmode is OFF.

Filterscripts
---------------
  Loaded 0 filterscripts.

My favourite vehicle is: 'Landstalker'!

You get the compiler output and the server output without ever needing to:

  • visit sa-mp.com/download.php
  • unzip a server package
  • worry about Windows or Linux differences
  • set up the Pawn compiler with your favourite editor
  • make sure the Pawn compiler is reading the correct includes
  • download the formatex include

See documentation for more info.

Server Configuration and Automatic Plugin Download

Use JSON or YAML to write your server config:

{
  "gamemodes": ["rivershell"],
  "plugins": ["maddinat0r/sscanf"],
  "rcon_password": "test",
  "port": 8080
}

It compiles to this:

gamemode0 rivershell
plugins sscanf.so
rcon_password test
port 8080
(... and the rest of the settings which have default values)

What also happens here is maddinat0r/sscanf tells sampctl to automatically get the latest sscanf plugin and place the .so or .dll file into the plugins/ directory.

See documentation for more info.