Pawn Studio — SA-MP / open.mp

🇧🇷 Leia em português

A complete Pawn environment for VS Code:

• compile from any file;
• syntax highlighting and IntelliSense;
• live error lens;
• a GitHub package manager with version ranges that installs plugins and includes from any repository;
• server debugging with crashdetect;
• tools: attached object editor (player and vehicle, in 3D), object finder (3D, search results and areas on the map), sprite finder, animation preview (3D), sound player, Dialog Creator and GangZone Creator.

The extension is available in English and Português (Brasil). It follows the VS Code display language, or you can force one with pawnStudio.language.

Compile from any file

The extension reads the #includes of the project (ignoring commented ones) and finds out which gamemode or filterscript uses the open file, even through several levels of modules. The status bar shows the target (▶ GM: main.pwn / ▶ FS: admin.pwn) and why it was chosen.

How the target is chosen, in order:

1. pinned target (Pawn: Pin compile target);
2. // @entry ../gamemodes/main.pwn at the top of the file;
3. the file is a main file;
4. the only main file that includes it (if several do, it asks once and remembers);
5. a file nobody includes yet → last target, the pawn.json entry, or the only gamemode.

A .pwn is a main file when:

• it has main() or #define FILTERSCRIPT, or
• it sits in gamemodes/ or filterscripts/ and defines OnGameModeInit / OnFilterScriptInit.

A candidate included by another main file is not a main file, so ALS hook modules are never mistaken for gamemodes.

"Pawn Studio" panel

Every compilation shows up in the Pawn Studio tab of the bottom panel (next to Problems, Output and Terminal):

• target, time and how long it took;
• the .amx size, and how much it grew or shrank since the previous build;
• the memory the script needs (header, code, data and stack/heap with the estimated use), from the pawncc summary;
• errors and warnings: click one to go to the line;
• under Details: the compiler, the include folders and the command line.

The same tab also keeps the package manager log and the server log of debug sessions. The chips on top filter by kind. pawnStudio.revealOutput chooses when the tab opens: on every compilation (default), only on errors, or never.

Live error lens

Errors show up at the end of the line while you type, with no need to save. There are two layers:

1. Quick analysis on every keystroke (~20 ms), done by the extension itself. It reports:

   • unmatched braces, parentheses and brackets;
   • unterminated strings;
   • missing ; (when the project uses -;+ / #pragma semicolon 1);
   • #includes that don't exist;
   • undefined functions, with a suggestion (did you mean "SetPlayerPos"?);
   • wrong argument counts.

   It understands multi-line strings with \, prefix macros (Dialog:, CMD:, Inventory: → IV_), y_timers, inline and static functions.

2. pawncc in the background, without saving:

   • compiles a temporary copy of the project that includes your unsaved text;
   • in large YSI gamemodes this takes as long as pawncc itself does, and the status bar shows pawncc 12s while it runs;
   • it isn't cancelled on every keystroke: it queues, and the results are adjusted to the edits you made while it was compiling.

Diagnostics follow the text: inserting lines moves them, and editing a line with an error clears it right away.

Syntax and IntelliSense

• Full grammar: tags (Float:), format specifiers (%d, %s, {FF0000}), packed strings, #define with %0, YSI keywords (hook, foreach, inline, timer) and CMD:.

• Autocomplete from the target's include tree, including file names inside #include <.

• Parameters filled in: accepting a function with Tab/Enter inserts its required parameters as fields, and Tab jumps between them:

  • SetPlayerPos(playerid, x, y, z);
  • GetPlayerName(playerid, name) (the len = sizeof name parameter has a default and is left out).

  Setting: pawnStudio.completion.parameters.

• Parameter hints, hover with docs (the stdlib XML comments are rendered), F12, outline and workspace symbol search.

• 54 snippets: SA-MP callbacks, dialogs, timers, commands, enums, foreach, hooks…

Package manager (GitHub)

It works like npm, with its own pawn.json format, and installs any GitHub repository.

A package doesn't need to have been written for Pawn Studio. When a repository has no pawn.json, the extension works out on its own:

• where the .inc files are (include/, pawno/include, or the repository root);
• which file in the release holds the plugin for your system:
  • Windows: -win32.zip, .dll;
  • Linux: -linux.tar.gz, .so;
  • 32-bit builds are preferred over 64-bit;
• what each file inside the archive is:
  • plugins (plugins/) are copied to plugins/ and registered in the server configuration;
  • open.mp components (components/) are copied to components/;
  • libraries the plugin needs (for example libmariadb.dll and log-core.dll from MySQL) go next to the server executable.

Search and install

In the Pawn sidebar, open Packages and click +:

• the search goes straight to GitHub (repositories with the pawn-package topic, plus SA-MP repositories);
• you pick the version:
  • ^2.9.6 (recommended): receives compatible updates;
  • an exact version;
  • a branch.

When a package is installed

• the code goes to .pawn-studio/dependencies/;
• plugins, components and libraries go to the server, as described above;
• plugins are registered in server.cfg (SA-MP) or config.json (open.mp);
• the include folders go to the compiler and to IntelliSense, with no configuration;
• the .inc files are also copied to the server's pawno/include (SA-MP) or qawno/include (open.mp), so pawno/qawno and other tools find them. A file that was already there and that Pawn Studio did not install is never overwritten, and the copies go away with the package. Turn it off with pawnStudio.packages.copyIncludes;
• packages that the package itself lists in its pawn.json are installed too. If your project asks for a different version of the same package, your version wins.

Updates

The view shows each package in one of these states:

• ✓: up to date.
• v2.9.4 → v2.9.6: a newer version fits the range in pawn.json. Updating it is safe.
• v2.9.6 · v3.0.0 available: a new major version exists outside the range. Updating asks for confirmation, because it may break your code, and then changes pawn.json to ^3.0.0.
• not installed: the package is in pawn.json but missing from .pawn-studio/dependencies/.

Lock file and removal

• pawn-lock.json: records the exact tag and commit of each package. Anyone who clones the project gets exactly the same code with Install pawn.json dependencies.
• Remove: deletes the files, plugins and libraries, removes the plugin from server.cfg, and cleans up dependencies that nothing uses anymore.

GitHub limits

Without signing in, GitHub allows 60 requests per hour and 10 searches per minute. Pawn: Sign in to GitHub uses the account already connected to VS Code and raises the limit to 5000 per hour.

Creating pawn.json

pawn.json lives in the server root (the folder that contains gamemodes/). It tells the extension:

• which file is the gamemode;
• where to write the .amx;
• which packages the project uses, and in which versions.

Option 1 — with the command (recommended)

1. Open the server folder in VS Code.
2. Run Pawn: Create pawn.json from the Command Palette (Ctrl+Shift+P), or click Create pawn.json in the Packages view.
3. The file is created with the detected gamemode:

{
	"name": "my-server",
	"version": "1.0.0",
	"entry": "gamemodes/main.pwn",
	"output": "gamemodes/main.amx",
	"dependencies": {}
}

You don't have to write the dependencies by hand. When you install a package with Install package..., the extension adds it to dependencies with the chosen version.

Option 2 — by hand

Create a pawn.json file in the server root. The editor validates it and autocompletes the fields as you type.

{
	"name": "my-server",
	"version": "1.0.0",
	"entry": "gamemodes/main.pwn",
	"output": "gamemodes/main.amx",
	"dependencies": {
		"samp-incognito/samp-streamer-plugin": "^2.9.6",
		"pBlueG/SA-MP-MySQL": "^R41-4",
		"pawn-lang/YSI-Includes": "branch:5.x"
	},
	"devDependencies": {
		"AmyrAhmady/samp-plugin-crashdetect": "^4.22"
	}
}

Then run Pawn: Install pawn.json dependencies (or the ☁ button in the Packages view).

Fields

Versions

The key is the GitHub repository (user/repo). The value says which version to install.

Tags in the v1.2.3 and 1.2.3 styles work, and so does the SA-MP style R41-4, which is read as 41.4. Pre-releases (-beta, -rc1) are only installed when the version you ask for names one.

What to commit

• ✅ pawn.json and pawn-lock.json: anyone who clones the project gets the same versions with Install pawn.json dependencies.
• ❌ .pawn-studio/: the downloaded packages. It is downloaded again from the lock, and it has its own .gitignore, so git skips it without you doing anything. (Projects from versions before 1.4 had a dependencies/ folder: the packages move to .pawn-studio/dependencies/ on their own.)

Publishing your own package

Find your case below, copy its pawn.json to the root of your repository and name the release files the same way. Then:

1. commit the pawn.json before creating the tag: installers read the pawn.json inside the tag (v1.0.0), not the one on your main branch;
2. create the GitHub release for that tag and attach the files;
3. run Pawn: Check my package (Packages view → ⋯): it lists what SA-MP and open.mp get on each system, and warns about anything missing;
4. add the pawn-package topic to the repository, so it shows up in the search.

A. Include only

No pawn.json and no release needed: push the repository and create version tags. The .inc files are found on their own (an include/ folder, or the repository root). Add a pawn.json only to list dependencies:

{ "dependencies": { "pawn-lang/samp-stdlib": "latest" } }

B. SA-MP plugin

Release files:

myplugin-1.0.0-win32.zip          myplugin-1.0.0-linux.tar.gz
├─ plugins/myplugin.dll           ├─ plugins/myplugin.so
└─ include/myplugin.inc           └─ include/myplugin.inc

{
	"supports": "samp",
	"plugins": {
		"windows": "myplugin-*-win32.zip",
		"linux": "myplugin-*-linux.tar.gz"
	}
}

C. open.mp component only

mycomponent-1.0.0-win32.zip       mycomponent-1.0.0-linux.tar.gz
├─ components/mycomponent.dll     ├─ components/mycomponent.so
└─ include/mycomponent.inc        └─ include/mycomponent.inc

{
	"supports": "openmp",
	"plugins": {
		"windows": "mycomponent-*-win32.zip",
		"linux": "mycomponent-*-linux.tar.gz"
	}
}

With "supports": "openmp", loose .dll/.so files at the root of the archive also count as components.

D. Plugin and component in the same file

One file per system, with both builds inside:

audio-cast-1.0.3-windows-x86.zip
├─ plugins/audio-cast.dll         ← SA-MP
├─ components/audio-cast.dll      ← open.mp
└─ include/audio-cast.inc

{
	"supports": ["samp", "openmp"],
	"plugins": {
		"windows": "audio-cast-*-windows-x86.zip",
		"linux": "audio-cast-*-linux-x86.zip"
	}
}

D2. One folder per server inside the archive

Each server's files in a folder of its own, as they would be laid out in that server:

PawnJson-1.0.0-windows-x86.zip
├─ samp/
│  ├─ plugins/PawnJson.dll
│  └─ pawno/include/PawnJson.inc
└─ open.mp/
   ├─ components/PawnJson.dll
   └─ qawno/include/PawnJson.inc

{
	"supports": ["samp", "openmp"],
	"plugins": {
		"windows": "PawnJson-*-windows-x86.zip",
		"linux": "PawnJson-*-linux-x86.zip"
	}
}

SA-MP uses only the samp/ folder (plugin, server.cfg and its include); open.mp uses only open.mp/ (component and its include). Folder names recognized: samp, sa-mp, legacy and open.mp, openmp, omp, at the root of the archive or one level down. With other folder names, declare them with layout.

G. Declare where each file is: layout

When the archive is organized your own way, say where each kind of file is, per server. Paths are relative to the archive root (a single top folder such as mylib-1.0/ is looked through):

mylib-1.0.0-win32.zip
└─ mylib-1.0.0/
   ├─ bin/legacy/mylib.dll
   ├─ bin/omp/mylib.dll
   ├─ inc/samp/mylib.inc
   ├─ inc/omp/mylib.inc
   └─ libs/libcurl.dll

{
	"supports": ["samp", "openmp"],
	"plugins": { "windows": "mylib-*-win32.zip", "linux": "mylib-*-linux.tar.gz" },
	"layout": {
		"samp":   { "plugins": "bin/legacy", "include": "inc/samp" },
		"openmp": { "components": "bin/omp/mylib.dll", "include": "inc/omp" },
		"all":    { "libraries": "libs/*.dll" }
	}
}

• Each value is a folder ("bin/legacy"), a pattern ("bin/omp/*.dll") or a list of them.
• samp is used on SA-MP servers, openmp on open.mp servers, all on both.
• Only the .dll (Windows) or .so (Linux) of the system being installed are taken from those folders.
• With layout, only what it lists is installed: no detection. A path that is not in the archive is reported in the install log and by Pawn: Check my package.

E. Plugin and component in separate files

myplugin-1.0.0-win32.zip          myplugin-omp-1.0.0-win32.zip
└─ plugins/myplugin.dll           └─ components/myplugin.dll

{
	"supports": ["samp", "openmp"],
	"plugins":    { "windows": "myplugin-*-win32.zip",     "linux": "myplugin-*-linux.tar.gz" },
	"components": { "windows": "myplugin-omp-*-win32.zip", "linux": "myplugin-omp-*-linux.tar.gz" }
}

SA-MP downloads only the plugins file; open.mp downloads only the components file. A file that a components pattern matches is never used as the plugin, even when the plugins pattern matches it too.

F. Several systems, architectures and variants

Add one key per build. The plain windows / linux keys are the 32-bit builds, which is what SA-MP and open.mp load:

{
	"plugins": {
		"windows":       "mylib-*-win32.zip",
		"windows-x64":   "mylib-*-win64.zip",
		"linux":         "mylib-*-linux-static.tar.gz",
		"linux-dynamic": "mylib-*-linux-dynssl.tar.gz"
	}
}

The project that installs the package chooses the build with "target" in its own pawn.json (see Project settings): { "os": "linux", "variant": "dynamic" }. A variant the package does not have falls back to the plain key of that system.

Reference

Keys of plugins / components: windows, linux, windows-x64, linux-x64, and variants such as linux-dynamic, linux-static or linux-x86-dynamic. A value can also be a list of patterns.

Inside the release file:

A pawn.json that already has sampctl fields (user, repo, include_path, resources) can keep them: add the Pawn Studio fields next to them and the same file serves both tools. Archives inside the release archive (a .tar.gz inside a .zip) are opened too.

When the release brings the .inc files, the repository source (SDKs, C++ code) is not kept in the installer's .pawn-studio/dependencies/ folder.

Project settings: target and compiler

The pawn.json of your project (in the server folder) can hold settings that belong to the project, so everyone who opens it gets the same:

{
	"entry": "gamemodes/main.pwn",
	"target": { "os": ["windows", "linux"] },
	"compiler": {
		"path": "pawno/pawncc.exe",
		"args": ["-d3", "-;+", "-(+"],
		"includes": ["pawno/include"]
	}
}

target — which builds packages install:

With several systems, the config file (server.cfg / config.json) is written for the server in the folder. A SA-MP server on Linux needs the .so in the name (plugins streamer.so): the install log shows that line for the other system.

compiler — path of pawncc, args and extra includes (paths relative to pawn.json). They win over the pawnStudio.compilerPath, pawnStudio.args and pawnStudio.includePaths settings.

Tools: objects, sprites, animations, sounds and dialogs

The Tools section of the Pawn sidebar opens seven tools. Every one inserts code at the cursor of the file you were editing.

The finders read models, textures, animations and sounds straight from your own GTA San Andreas installation: nothing from the game is bundled with the extension. The game folder is detected on its own (SA-MP's registry key, then common install folders). If it isn't found, pick it with Pawn: Select the GTA San Andreas folder or the pawnStudio.gtaPath setting. To use another copy of the game later, click Change folder at the top right of the finders, or the GTA San Andreas item at the end of the Tools section (it shows the folder in use).

Results on the map: every place where the objects you searched for are, with the real position and rotation.

Object preview with the game's own textures:

Attached Objects: position objects on the player or on a vehicle in 3D.

GangZone Creator: rectangles, circles and polygons, with streamer areas.

Dialog Creator: a preview that looks like the game.

Animations in 3D on any skin, and sounds that play in the editor:

• Dialog Creator details:
  • With the cursor on an existing ShowPlayerDialog or Dialog_Show, the creator opens filled in with that dialog. It's also in the editor's right-click menu.
  • The code style follows your project: easyDialog when it already uses Dialog_Show.
  • Long texts are built with strcat, so no line goes over the compiler's limit.
• Dialog text: type \t and \n like in Pawn, or press Tab in the text box. Both become columns in TABLIST dialogs. SA-MP shows at most 4 columns (3 tabs per row): the Dialog Creator warns about longer rows and leaves the extra columns out of the code.
• Attached Objects: the editor comes from SA-MP Preview Studio, with the models read from your game. With the cursor on SetPlayerAttachedObject or AttachObjectToVehicle lines (or with them selected), run Pawn: Attached Objects or use the right-click menu: they open in the editor, and Insert all in the editor writes the result back. Shortcuts: W move, E rotate, R scale, F focus.
• Custom skins and models: the game models are read the way the game loads them: first the modloader/ folder (loose .dff/.txd, and new skin ids from its .ide files), then the extra IMGs in data/gta.dat, then the stock archives. So a skin replaced with modloader or inside gta3.img shows up in place of the original, in the attachment editor and in the animation preview. The server's own models also appear, marked custom: AddCharModel (skins 20001+) and AddSimpleModel (objects, negative ids) from models/artconfig.txt or from the gamemode code.
• Which sounds play: the link between a sound ID and the audio banks is built into gta_sa.exe. The extension ships that table, rebuilt from the reverse-engineered game code (gta-reversed). Each ID is marked:
  • 🔊 the game plays it from its resident banks, so it is what players hear;
  • 🔇 it needs a mission audio bank that a game script loads, so it is usually silent on SA-MP;
  • 🎵 it starts a streamed music track;
  • no mark: nothing audible.
• Map area: the map is the game's own radar image. Placements come from the game's IPL files (text IPLs plus the binary stream IPLs inside gta3.img). The generated RemoveBuildingForPlayer lines include the LOD models, so buildings don't stay visible from far away.
• Results on the map: click Results on the map under the search box. Every object the search and filters find shows up on the map, one color per model. Click a model in the list to see only its positions (as a table), or click a dot to get its coordinates, CreateObject with the same rotation, RemoveBuildingForPlayer and SetPlayerPos. Insert the positions writes all of them as a Pawn array, handy to build a system around the game's own gas pumps, ATMs or doors. The rotation is converted from the IPL quaternion to the rotX, rotY, rotZ that CreateObject uses.
• Map zoom: every map has a zoom bar on the right (+, slider, −, whole map), so the mouse wheel is not needed. Double-click also zooms in.
• GangZone Creator: SA-MP only draws rectangular gang zones, so circles and polygons become horizontal strips that do not overlap (choose how many; the total is checked against the 1024 gang zone limit). The streamer areas follow the exact shape. The generated code has Zones_Create(), Zones_Show(playerid) and Zones_Hide(playerid) (or the ForAll versions). With the cursor on GangZoneCreate or CreateDynamic* lines, run Pawn: GangZone Creator or use the right-click menu to open them in the editor; the code it generates opens again with the same shapes. Shortcuts: V select, R rectangle, C circle, P polygon, H move the map, Delete removes, Ctrl+D duplicates.

Debugging the server

F6, the ▶ button in the Server view, or Run and Debug → SA-MP / open.mp Server:

1. compiles the gamemode (and stops if there are errors);
2. warns if server.cfg loads a different gamemode;
3. starts samp-server.exe / omp-server.exe and streams the log to the Debug Console;
4. when crashdetect reports an error (array index out of bounds, native failed, hang…):
   • VS Code stops at the exact line with the error message and a hint;
   • the call stack shows each function with its file and line;
   • the Variables view shows each function's arguments (playerid = 0, cmdtext = "/test");
   • the server keeps running: Continue (F5) moves on;
5. the Debug Console REPL sends commands to the server: via RCON on SA-MP (needs rcon_password), via the console on open.mp.

SA-MP doesn't support breakpoints or stepping. The debugger shows where and why an error happened. Install crashdetect (search "crashdetect" in Packages) and keep -d3 in the compiler arguments.

"Pawn" sidebar

• Compilation:
  • result of the last compilation or check, with duration and time;
  • target and .amx size;
  • clickable errors and warnings;
  • compiler and include folders.
• Packages: direct and indirect dependencies with their state (installed, up to date, update available, missing), plugins and include paths, with inline actions.
• Server:
  • running or stopped;
  • executable (SA-MP or open.mp), server.cfg, gamemode and port;
  • server log;
  • plugins, warning when a file is missing from plugins/;
  • history of runtime errors with a clickable call stack.

Settings

Development

npm install
npm test            # unit + grammar + translation tests
npm run test:live   # real GitHub integration (installs crashdetect + streamer in a temp folder)
npm run test:vscode -- <pawncc.exe> <include-folder>...   # runs everything inside a real VS Code
npm run package     # builds the .vsix

Translations

• Code messages use t('English text {0}', value) (src/i18n.ts). Translations live in l10n/bundle.l10n.<locale>.json.
• Menus and settings use package.nls.json / package.nls.<locale>.json.
• npm test fails if a message has no translation or the placeholders don't match.
• To add a language, copy the pt-br files, translate them, and add the locale to the pawnStudio.language setting.