### Clone and Setup GitHub Package

Source: https://context7.com/southclaws/sampctl/llms.txt

Clones a package directly from a GitHub repository and automatically executes `sampctl ensure` to download and set up its dependencies. This is a convenient way to quickly start working with existing projects.

```bash
# Clone a package and ensure dependencies
sampctl get Southclaws/samp-logger

# Clone to a specific directory
sampctl get Southclaws/samp-logger --dir ./packages/logger

# This is equivalent to:
# git clone https://github.com/Southclaws/samp-logger
# cd samp-logger
# sampctl ensure
```

--------------------------------

### Build and Run Pawn Project - Bash

Source: https://github.com/southclaws/sampctl/blob/master/docs/quickstart.md

Builds the Pawn project into an executable (e.g., .amx file) and then runs it, typically starting a server.

```bash
sampctl build
sampctl run
```

--------------------------------

### Install Scoop Package Manager

Source: https://github.com/southclaws/sampctl/wiki/Windows

Downloads and installs the Scoop package manager for Windows. This command uses .NET WebClient to download and execute the installation script.

```powershell
iex (new-object net.webclient).downloadstring('https://get.scoop.sh')
```

--------------------------------

### Example JSON Build Configuration

Source: https://github.com/southclaws/sampctl/blob/master/docs/build-configuration-reference.md

An example of a single build configuration in JSON format. It specifies the entry point, output path, and compiler settings including debug level.

```json
{
  "entry": "gamemodes/main.pwn",
  "output": "gamemodes/main.amx",
  "build": {
    "compiler": { "preset": "samp" },
    "options": {
      "debug_level": 3
    }
  }
}
```

--------------------------------

### Install Dependencies with sampctl

Source: https://github.com/southclaws/sampctl/blob/master/docs/configuration.md

Ensures that all declared plugins and components are downloaded and installed. This command should be run after modifying dependencies in `pawn.json` or `pawn.yaml`.

```bash
sampctl ensure
```

--------------------------------

### Add sampctl Bucket and Install sampctl with Scoop

Source: https://github.com/southclaws/sampctl/wiki/Windows

Adds the sampctl Git repository as a Scoop bucket and then installs sampctl. This command requires Scoop to be installed first.

```powershell
scoop bucket add sampctl https://github.com/Southclaws/sampctl.git; scoop install sampctl
```

--------------------------------

### Initialize Pawn Project - Bash

Source: https://github.com/southclaws/sampctl/blob/master/docs/quickstart.md

Initializes a new Pawn project (package) in the current directory. Supports presets like 'openmp' for alternative server types.

```bash
sampctl init
```

```bash
sampctl init --preset openmp
```

--------------------------------

### sampctl Get Command (Bash)

Source: https://github.com/southclaws/sampctl/blob/master/docs/packages.md

Clones a Pawn package directly from a GitHub repository and ensures its dependencies are installed. This is useful for fetching external packages.

```bash
# Get and install dependencies for a GitHub package
sampctl get Southclaws/formatex
```

--------------------------------

### Build and Run Specific Configurations

Source: https://context7.com/southclaws/sampctl/llms.txt

Commands for building specific configurations or running defined runtime environments within an advanced package setup. Allows targeted execution of builds or server instances.

```bash
# Build specific configuration
sampctl build debug

# Run specific runtime
sampctl run production

# Run tests
sampctl run testing
```

--------------------------------

### Install sampctl on Debian/Ubuntu via .deb

Source: https://github.com/southclaws/sampctl/wiki/Linux

Installs sampctl on Debian-based systems using a .deb package. This script fetches the latest release, downloads the .deb file, and installs it using dpkg.

```bash
curl https://raw.githubusercontent.com/Southclaws/sampctl/master/scripts/install-deb.sh | sh
```

--------------------------------

### Download sampctl Linux Binary

Source: https://github.com/southclaws/sampctl/wiki/Linux

Provides instructions for manually installing the sampctl Linux binary for systems not covered by package managers. The statically compiled binary can be downloaded from GitHub releases and placed in a bin directory.

```bash
# Download the latest Linux binary from https://github.com/Southclaws/sampctl/releases
# Example: wget https://github.com/Southclaws/sampctl/releases/download/v1.13.0/sampctl_linux_amd64.tar.gz
# Extract and move to a bin directory
```

--------------------------------

### Pawn Project Dependencies - JSON

Source: https://github.com/southclaws/sampctl/blob/master/docs/quickstart.md

Defines the entry point, output file, and dependencies for a Pawn project using a JSON configuration file.

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

--------------------------------

### sampctl Quick Start Commands (Bash)

Source: https://github.com/southclaws/sampctl/blob/master/README.md

This snippet shows the basic commands to initialize, ensure dependencies, and run a project using sampctl. It assumes a Unix-like environment where the sampctl binary is accessible.

```bash
sampctl init
sampctl ensure
sampctl run
```

--------------------------------

### CI Workflow for Pawn Projects with GitHub Actions

Source: https://context7.com/southclaws/sampctl/llms.txt

This GitHub Actions workflow automates the building and testing of Pawn projects using sampctl. It handles dependency installation, compilation, and testing, making it suitable for continuous integration.

```yaml
# .github/workflows/ci.yml
name: CI

on:
  push:
    branches: [main, develop]
  pull_request:

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Install sampctl
        run: |
          curl -fsSL https://raw.githubusercontent.com/Southclaws/sampctl/master/scripts/install-deb.sh | bash

      - name: Install 32-bit support
        run: |
          sudo dpkg --add-architecture i386
          sudo apt-get update
          sudo apt-get install -y g++-multilib

      - name: Ensure dependencies
        run: sampctl ensure

      - name: Build project
        run: sampctl build

      - name: Run tests
        run: sampctl run testing --forceBuild --forceEnsure
        env:
          RCON_PASSWORD: ${{ secrets.RCON_PASSWORD }}

      - name: Upload artifacts
        uses: actions/upload-artifact@v4
        with:
          name: gamemode
          path: gamemodes/*.amx

```

--------------------------------

### List Compiler Configurations

Source: https://context7.com/southclaws/sampctl/llms.txt

Displays all detected Pawn compiler configurations available to sampctl. This helps in identifying which compiler versions are installed and selectable for project builds.

```bash
# List all compiler configurations
sampctl compiler list

# Example output:
# • Pawn compiler 3.10.10 (default)
# • Pawn compiler 3.10.11
# • Pawn compiler 3.2.3664
```

--------------------------------

### Install Private Repository via SSH (PowerShell)

Source: https://github.com/southclaws/sampctl/wiki/Modern-Pawn

Installs a package from a private Git repository using its SSH URL. This method relies on SSH keys being set up correctly for authentication. The command supports standard Git versioning suffixes like ':', '@', and '#'.

```powershell
sampctl package install git@gitlab.com:Southclaws/pawn-private.git
```

--------------------------------

### YAML Build Configuration with Plugins

Source: https://github.com/southclaws/sampctl/blob/master/docs/build-configuration-reference.md

Demonstrates how to define plugins (pre-compile commands) within a YAML build configuration. This example shows a simple 'echo' command to be run before compilation.

```yaml
build:
  plugins:
    - ["echo", "hello"]
```

--------------------------------

### Example Build Configuration for Includes

Source: https://github.com/southclaws/sampctl/wiki/Legacy-Includes

A fragment of a sampctl package definition file showing a basic 'builds' configuration. The 'includes' field specifies directories to be used as include paths during the compilation process. This example assumes a build named 'main' and includes a directory named 'includes'.

```json
  "builds": [
    {
      "name": "main",
      "includes": ["includes"]
    }
  ]
```

--------------------------------

### Docker Compose Example for Server Deployment

Source: https://context7.com/southclaws/sampctl/llms.txt

This docker-compose.yml configuration defines a service for deploying the gamemode container. It allows for port mapping, environment variable configuration, volume mounting, and defining restart policies.

```yaml
# docker-compose.yml
version: '3'
services:
  gamemode:
    build: .
    ports:
      - "7777:7777/udp"
    environment:
      - RCON_PASSWORD=secure_password
    volumes:
      - ./scriptfiles:/app/scriptfiles
    restart: unless-stopped

```

--------------------------------

### Initialize sampctl Package

Source: https://github.com/southclaws/sampctl/blob/master/docs/library-creator-guide.md

Initializes a new sampctl package in the current directory. For libraries, the 'entry' should be a test or demo script, not the include file itself.

```bash
sampctl init
```

--------------------------------

### Install SA:MP Standard Library Package with sampctl

Source: https://github.com/southclaws/sampctl/wiki/FAQ

This command installs the SA:MP standard library package, which is necessary for resolving 'fatal error 100: cannot read from file: "a_samp"' during builds. It also shows how to specify a version tag for compatibility with specific SA:MP server versions.

```bash
sampctl package install sampctl/samp-stdlib
sampctl package install sampctl/samp-stdlib:0.3.7-R2-2-1
```

--------------------------------

### SA:MP Runtime Configuration JSON Example

Source: https://github.com/southclaws/sampctl/wiki/Servers-Quickstart

An example of a SA:MP runtime configuration in JSON format. This file defines gamemodes, plugins, server port, hostname, and player limits. It is used by sampctl to generate the 'server.cfg'.

```json
{
  "gamemodes": ["cnr"],
  "plugins": ["crashdetect", "sscanf", "streamer"],
  "port": 7777,
  "hostname": "My Awesome Server",
  "maxplayers": 32,
  "rcon": false,
  "rcon_password": "test"
}
```

--------------------------------

### Ensure and Run Library Demo

Source: https://github.com/southclaws/sampctl/blob/master/docs/library-creator-guide.md

Ensures all dependencies are met and then runs the library's demo script. This is useful for 'demo tests' where the entry script acts as a small gamemode.

```bash
sampctl ensure
sampctl run
```

--------------------------------

### Configure Library for Unit Testing

Source: https://github.com/southclaws/sampctl/blob/master/docs/library-creator-guide.md

Sets the runtime mode in 'pawn.json' to 'y_testing' to enable unit testing with the y_testing framework.

```json
{
  "runtime": {
    "mode": "y_testing"
  }
}
```

--------------------------------

### Pawn Include Directives for Dependencies

Source: https://github.com/southclaws/sampctl/wiki/Quickstart

Example Pawn code demonstrating how to include external libraries using the #include directive. These lines are used by sampctl during dependency scanning to identify required packages.

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

--------------------------------

### GitHub Actions CI Workflow for sampctl (YAML)

Source: https://github.com/southclaws/sampctl/blob/master/docs/ci.md

A GitHub Actions workflow for automating the CI process for sampctl projects on Ubuntu. It includes steps to install sampctl, set up optional 32-bit architecture, ensure dependencies, build the project, and optionally run tests.

```yaml
name: CI

on:
  push:
  pull_request:

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Install sampctl
        run: |
          curl -fsSL https://raw.githubusercontent.com/Southclaws/sampctl/master/scripts/install-deb.sh | bash

      # Some Pawn toolchains/runtimes are 32-bit; you may need i386 support on Linux.
      - name: Install 32-bit support (optional)
        run: |
          sudo dpkg --add-architecture i386
          sudo apt-get update
          sudo apt-get install -y g++-multilib

      - name: Ensure
        run: sampctl ensure

      - name: Build
        run: sampctl build

      - name: Run (optional)
        run: sampctl run --forceBuild --forceEnsure

```

--------------------------------

### Example sampctl Cache Directory Structure (Bash)

Source: https://github.com/southclaws/sampctl/wiki/Cache

Illustrates the typical file and directory layout within the sampctl cache. This includes compilers, plugins, and runtime environments.

```bash
├── pawn
│   └── 3.10.4
│       ├── libpawnc.dylib
│       ├── pawnc-3.10.4-darwin
│       └── pawncc
├── pawnc-3.10.4-darwin.zip
├── plugins
│   ├── samp-plugin-crashdetect
│   │   └── latest
│   └── samp-streamer-plugin
│       └── latest
├── runtime
│   └── 0.3.7
└── samp037svr_R2-2-1.tar.gz
```

--------------------------------

### Example Extra Settings in JSON Configuration

Source: https://github.com/southclaws/sampctl/wiki/Runtime-Configuration-Reference

This snippet demonstrates how to include extra configuration options, such as a Discord bot token, within the `extra` field of a JSON runtime configuration. These settings are intended for use by plugins or other external services.

```json
{
  "extra": {
    "discord_token": "abc123"
  }
}
```

--------------------------------

### Default sampctl Package Definition File Structure

Source: https://github.com/southclaws/sampctl/wiki/Legacy-Includes

An example of a typical sampctl package definition file in JSON format before modifications. This structure outlines the basic configuration for a package, including user, repository, entry point, output file, and dependencies.

```json
{
  "user": "Southclaws",
  "repo": "myserver",
  "entry": "gamemodes/gamemode.pwn",
  "output": "gamemodes/gamemode.amx",
  "dependencies": ["sampctl/samp-stdlib"]
}
```

--------------------------------

### TravisCI Configuration for Pawn Packages with sampctl

Source: https://github.com/southclaws/sampctl/wiki/Continuous-Integration

This YAML configuration sets up TravisCI to build and test Pawn packages using sampctl. It ensures the necessary dependencies, including sampctl itself and multilib support, are installed before executing build and test commands.

```yaml
language: cpp
sudo: enabled
install:
- curl https://raw.githubusercontent.com/Southclaws/sampctl/master/install-deb.sh | sh
- sudo dpkg --add-architecture i386
- sudo apt update && sudo apt install -y g++-multilib
script:
- sampctl package ensure
- sampctl package build
- sampctl package run
```

--------------------------------

### Minimal pawn.json for Includes-Only Library

Source: https://github.com/southclaws/sampctl/blob/master/docs/library-creator-guide.md

Defines a minimal package for an includes-only library. It specifies the entry point for compilation, the output file, and essential dependencies like the standard Pawn library.

```json
{
  "entry": "test.pwn",
  "output": "test.amx",
  "dependencies": ["pawn-lang/samp-stdlib"],
  "runtime": {
    "mode": "main"
  }
}
```

--------------------------------

### Run Library Unit Tests

Source: https://github.com/southclaws/sampctl/blob/master/docs/library-creator-guide.md

Executes the library's unit tests using sampctl. The --forceEnsure and --forceBuild flags ensure tests run with the latest code.

```bash
sampctl run --forceEnsure --forceBuild
```

--------------------------------

### JSON Configuration for Plugin Resources

Source: https://github.com/southclaws/sampctl/blob/master/docs/plugin-resources.md

This JSON configuration defines resources for sampctl to download and install plugin binaries. It specifies include paths and plugin binary locations within archives for different platforms.

```json
{
  "entry": "test.pwn",
  "output": "test.amx",
  "dependencies": ["pawn-lang/samp-stdlib"],
  "resources": [
    {
      "name": "^my-plugin-(.*)\\.zip$",
      "platform": "windows",
      "archive": true,
      "includes": ["pawno/include"],
      "plugins": ["plugins/my-plugin.dll"]
    },
    {
      "name": "^my-plugin-(.*)\\.tar.gz$",
      "platform": "linux",
      "archive": true,
      "includes": ["pawno/include"],
      "plugins": ["plugins/my-plugin.so"]
    }
  ]
}
```

--------------------------------

### Ensure SA:MP Server Setup with sampctl

Source: https://github.com/southclaws/sampctl/wiki/Servers-Quickstart

Triggers the 'ensure' process for a SA:MP runtime. This command verifies and sets up all necessary components, including downloading and installing plugins based on the runtime configuration.

```powershell
sampctl server ensure
```

--------------------------------

### Install Sampctl using Homebrew

Source: https://github.com/southclaws/sampctl/wiki/Mac

Installs the sampctl package manager on macOS using Homebrew. Requires Homebrew to be installed beforehand. This command adds the necessary tap and installs the package.

```bash
brew install Southclaws/sampctl/sampctl
```

--------------------------------

### Install sampctl on Fedora/CentOS/RHEL via .rpm

Source: https://github.com/southclaws/sampctl/wiki/Linux

Installs sampctl on RPM-based systems like Fedora and CentOS. The process involves downloading the latest .rpm release and installing it.

```bash
curl https://raw.githubusercontent.com/Southclaws/sampctl/master/scripts/install-rpm.sh | sh
```

--------------------------------

### Initialize a Pawn Package with sampctl

Source: https://github.com/southclaws/sampctl/wiki/Quickstart

Initializes a new Pawn package or converts an existing project into a package. This command prompts the user for configuration details and generates a Package Definition File (JSON or YAML). It's essential for setting up project structure and dependencies.

```powershell
sampctl package init
```

--------------------------------

### Set PowerShell Execution Policy

Source: https://github.com/southclaws/sampctl/wiki/Windows

Allows PowerShell to execute local scripts, a prerequisite for installing Scoop.

```powershell
set-executionpolicy remotesigned -scope currentuser
```

--------------------------------

### Docker Container Build and Run Commands

Source: https://context7.com/southclaws/sampctl/llms.txt

These bash commands demonstrate how to build a Docker image for your gamemode and run it as a container. It includes port mapping for external access.

```bash
# Build and run container
docker build -t my-gamemode .
docker run -p 7777:7777/udp my-gamemode

```

--------------------------------

### Filterscript Dependency Scheme - JSON

Source: https://github.com/southclaws/sampctl/blob/master/docs/dependency-schemes.md

The 'filterscript://user/repo' scheme installs a repository's compiled script as a filterscript. sampctl ensures the package, builds it, and installs the resulting .amx into './filterscripts/'.

```json
{
  "dependencies": ["filterscript://SomeUser/some-filterscript"]
}
```

--------------------------------

### Update SA:MP Plugins using GitHub Syntax in JSON

Source: https://github.com/southclaws/sampctl/wiki/Servers-Quickstart

Demonstrates how to specify plugins for automatic download and installation using GitHub repository syntax within the SA:MP runtime configuration (JSON). sampctl automatically handles platform-specific binaries (.so for Linux).

```json
{
  "gamemodes": ["cnr"],
  "plugins": [
    "Zeex/samp-plugin-crashdetect",
    "maddinat0r/sscanf",
    "samp-incognito/samp-streamer-plugin"
  ],
  "port": 7777,
  "hostname": "My Awesome Server",
  "maxplayers": 32,
  "rcon": false,
  "rcon_password": "test"
}
```

--------------------------------

### Install Dependencies with sampctl

Source: https://github.com/southclaws/sampctl/wiki/Quickstart

Installs specified packages as dependencies for your Pawn project. This is used to add external libraries or the SA:MP standard library to your project's dependency list, ensuring they are available for compilation.

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

--------------------------------

### Manage Package Templates

Source: https://context7.com/southclaws/sampctl/llms.txt

Facilitates the creation and utilization of package templates for rapid project scaffolding and the execution of standalone Pawn files. Templates help in setting up recurring project structures or running quick tests.

```bash
# Create a template from current package
sampctl template make my-template

# Build a file using a template
sampctl template build my-template test.pwn

# Run a file using a template (builds and executes)
sampctl template run my-template test.pwn

# Example use case: quick testing of Pawn snippets
# 1. Create a template with common dependencies
# 2. Run any .pwn file with those dependencies without setup
```

--------------------------------

### Build Library with sampctl

Source: https://github.com/southclaws/sampctl/blob/master/docs/library-creator-guide.md

Compiles the library's Pawn code. This is used for fast compilation checks during development.

```bash
sampctl build
```

--------------------------------

### Update sampctl using Scoop

Source: https://github.com/southclaws/sampctl/wiki/Windows

Updates the Scoop metadata and then upgrades the sampctl application to the latest version available in its bucket.

```powershell
scoop update
scoop update sampctl
```

--------------------------------

### Create Versioned Release with sampctl

Source: https://github.com/southclaws/sampctl/blob/master/docs/library-creator-guide.md

Initiates an interactive process to create a versioned release for the library. This typically involves tagging the release.

```bash
sampctl release
```

--------------------------------

### Dockerfile for SA:MP/open.mp Server Deployment

Source: https://context7.com/southclaws/sampctl/llms.txt

This Dockerfile sets up a containerized environment for deploying SA:MP or open.mp servers using sampctl. It copies project files, ensures dependencies, builds the project, and exposes the server port.

```dockerfile
# Dockerfile
FROM southclaws/sampctl:latest

WORKDIR /app

COPY pawn.json pawn.yaml* ./
COPY *.pwn ./
COPY gamemodes/ ./gamemodes/

RUN sampctl ensure

RUN sampctl build

EXPOSE 7777/udp

CMD ["sampctl", "run", "--container"]

```

--------------------------------

### Run sampctl Package Tests

Source: https://github.com/southclaws/sampctl/wiki/Quickstart

Automatically builds and runs your package tests by setting up a local server with your `test.pwn` as the gamemode. This command simplifies the testing process, removing the need for manual server configuration. The `--forceBuild` flag ensures the script is compiled before running.

```bash
sampctl package run --forceBuild
```

```bash
sampctl package run --forceEnsure --forceBuild
```

--------------------------------

### Update Sampctl using Homebrew

Source: https://github.com/southclaws/sampctl/wiki/Mac

Updates the Homebrew taps and then upgrades the sampctl package to the latest version. This ensures you have the most recent features and bug fixes.

```bash
brew update
brew upgrade sampctl
```