Quick Start

Create an Application

This section describes how to set up an Infernus application locally.

We strongly recommend using the infernus-starter template to scaffold a simple TypeScript project.

You should have basic familiarity with native Pawn development and Node.js.

CLI

The project uses pnpm to manage dependencies, so you'll need to install pnpm first.

You can easily create a project by following the command-line prompts.

pnpm dlx @infernus/cli@latest create

TIP

Since the CLI internally calls the GitHub HTTP API, it may fail to create the app if your network connection is unreliable. In that case, refer to the Manual section.

Learn about API rate limits

@infernus/cli is a tool similar to sampctl that manages package dependencies by parsing pawn.json rules. You can use it to manage plugin and open.mp base dependencies with ease.

Cache

WARNING

The cache generated by pnpm dlx can be overly persistent. It is recommended to manually delete the dlx cache from time to time — otherwise, even specifying @latest may still run an outdated version.

Windows: C:\Users\%USERNAME%\AppData\Local\pnpm-cache\dlx
Linux: ~/.cache/pnpm/dlx

View cache directory

Example

# Install the CLI tool globally
pnpm add @infernus/cli -g
# Update if already installed globally
pnpm update @infernus/cli -g

# Create a project
infernus create <appName>

# Install one or more dependencies.
# All operations can specify a version number, similar to npm package syntax.
infernus add openmultiplayer/open.mp dockfries/samp-streamer-plugin@^2.9.6
# Install a component dependency
infernus add dockfries/Pawn.RakNet@^1.7.0-omp --component
# Production mode (does not copy inc files)
infernus add dockfries/samp-streamer-plugin@^2.9.6 -p

# Install all existing dependencies (similar to sampctl ensure)
infernus install

# Same as above, production mode (no inc files copied)
infernus install -p

# Install exactly what the lockfile records, and fail when it no longer
# satisfies the manifest (the `npm ci` of this CLI)
infernus install --frozen

# Uninstall one or more dependencies
infernus remove openmultiplayer/open.mp dockfries/samp-streamer-plugin
infernus remove dockfries/Pawn.RakNet

# Move every declared dependency inside its range, and rewrite the lockfile
infernus update

# Update a dependency (updates global cache and applies to current directory)
infernus update openmultiplayer/open.mp

# Update a dependency to a specific version
infernus update openmultiplayer/open.mp@^1.6.7

# Add a dependency without a version: the manifest gets the range npm would
# write (^2.8.1), or the exact tag with --save-exact
infernus add dockfries/samp-node
infernus add dockfries/samp-node --save-exact

# List the versions a dependency can be installed from
# (which ones satisfy the manifest, and which one is installed)
infernus versions
infernus versions openmultiplayer/open.mp --all

# Preview what an install or update would do: resolve only, nothing is
# downloaded and no file is written
infernus update openmultiplayer/open.mp@^1.6.7 --dry-run --verbose

# Print every cache decision and GitHub request, for version resolution problems
infernus update openmultiplayer/open.mp@^1.6.7 --verbose

# Clear every version of a single global dependency that a range matches
infernus clean dockfries/samp-streamer-plugin@^2.9.6
# Clear all versions of a single global dependency
infernus clean dockfries/samp-streamer-plugin
# Clear all global cache dependencies
infernus clean -a

# Set a GitHub token to resolve API rate limit issues (on-demand).
# Note: the `gh_token` environment variable takes precedence over the global config.
infernus config gh_token <your_github_token>

# Display global configuration
infernus config -l

# Delete a global configuration
infernus config gh_token

WARNING

In Windows cmd.exe the caret is an escape character, so @^1.6.7 reaches the CLI as @1.5.8 and you get a confusing "version not found" style error. Quote the version: infernus update "openmultiplayer/open.mp@^1.6.7"

How versions are written

infernus.json holds an npm style semver range (*, ^1.5.8, ~1.6.7), and may also name one release tag to pin that exact build.
Mixing 2.6.1 and ^2.9.6 in one file is normal: the CLI never rewrites a spec. 2.6.1 is an exact pin, so update stays on that release; ^2.9.6 is a range, so update walks forward to the newest release it allows. To follow releases, add the range: infernus add dockfries/samp-node@^2.6.1. infernus versions shows which releases satisfy what the manifest declares.
infernus-lock.json holds the real GitHub release tag, for example v1.6.7.3218. open.mp tags four segments (vmajor.minor.patch.build), so 1.6.7 is not a tag at all; the CLI falls back to matching it as a range and picks v1.6.7.3218, which --verbose prints step by step.
The lockfile decides what an install may move, the way package-lock.json does for npm: an entry whose release still satisfies the manifest is installed as recorded, without resolving the release again, and only entries missing from the lockfile or no longer accepted by the manifest are resolved. infernus update is what resolves the declared ranges again and rewrites the lockfile; infernus install --frozen reproduces the lockfile as it is and refuses a project that it no longer describes.
An install is idempotent: a dependency whose release is already installed, and whose files are still in place, is left alone, so plugin binaries and includes the project edited are not rewritten. The files are checked rather than assumed, so a fresh clone (a committed lockfile and no plugins/) is still filled in.
infernus update without arguments moves every declared dependency inside its range and rewrites the lockfile; infernus update <pkg> does the same for one of them.
infernus add <pkg> without a version declares the range npm would write (^2.8.1), and --save-exact declares the exact tag instead. A dependency the manifest already declares keeps its spec: naming it without a version never widens what the project asked for.
Upgrading open.mp replaces the files the previous build shipped. Files the project changed are kept and listed, and config.json, bans.json and gamemodes/ are never overwritten. When the project config is rewritten, a config.json.<timestamp>.bak copy is left behind.

JSON Schema

Both infernus.json and infernus-lock.json have validation and completion available. Add one line at the top of the file:

json

{
  "$schema": "https://raw.githubusercontent.com/dockfries/infernus/main/packages/cli/schemas/infernus.schema.json",
  "dependencies": {
    "openmultiplayer/open.mp": "^1.6.7"
  }
}

Features

Only handles basic plugin dependency management — does not manage pure include libraries.
Installed packages are cached in ~/infernus/dependencies; subsequent installations of the same version copy from cache instead of re-downloading.
Configuration is stored in ~/infernus/config.json, which currently only contains a gh_token setting to address GitHub API rate limits.

Manual

# Clone via HTTPS
git clone https://github.com/dockfries/infernus-starter.git
# or via SSH
git clone git@github.com:dockfries/infernus-starter.git

# If you need raknet, clone the raknet branch
# git clone https://github.com/dockfries/infernus-starter.git -b raknet
# or use SSH
# git clone git@github.com:dockfries/infernus-starter.git -b raknet

# You can also download the repository directly from the GitHub page.

# Enter the project root directory
cd infernus-starter

# Modify the rcon password in config.json.
vim config.json # you don't have to use vim; any editor is fine.

# "rcon": {
#   "password": "changeme" # change changeme to your own password.
#}

WARNING

The repository has removed the necessary files to ensure you always use the latest dependency versions and to reduce repository size. This means you'll need to supply the files manually.

The so/dll files depend on your target server environment — choose the appropriate version accordingly. Linux only needs so; Windows only needs dll.

Download the omp game server, then extract omp-server[.exe] and the components folder into the project root.
Download the samp-node plugin, then extract libnode.so/dll into the project root and samp-node.so/dll into the plugins folder (create it if it doesn't exist).
Download the streamer plugin, then place streamer.so/dll in the plugins folder.
(If you need raknet) download the raknet component, then place all files except .inc files into the components folder.
1. Replace gamemodes/polyfill_raknet.amx with gamemodes/polyfill.amx, or modify the pawn.main_scripts section in config.json.

json

  "pawn": {
    "main_scripts": ["polyfill_raknet 1"],
  },

Install Dependencies & Dev

TIP

If you are using a 32-bit samp-node, you need to set specific environment variables before running pnpm install. See Ecosystem → 64-bit Experimental Support for details.

# Install dependencies
pnpm install

# Run development mode (compile, watch for changes, auto-restart)
pnpm dev

Build

# Build for production
pnpm build

# Run the server
pnpm serve

Quick Start ​

Create an Application ​

CLI ​

Cache ​

Example ​

How versions are written ​

JSON Schema ​

Features ​

Manual ​

Install Dependencies & Dev ​

Build ​

Quick Start

Create an Application

CLI

Cache

Example

How versions are written

JSON Schema

Features

Manual

Install Dependencies & Dev

Build