BurnsCommon Documentation

Developer guide for the BurnsCommon shared utility framework

Overview

BurnsCommon is a shared utility library for LSPDFR / RagePluginHook plugins. It provides common functionality so you don't have to rewrite the same code in every plugin.

Instead of every plugin re-implementing logging, dependency checks, config parsing, update logic, and UI systems, BurnsCommon centralizes all of it into a single lightweight framework.

The result: smaller plugins, fewer conflicts, faster development, and a more stable experience for players.

Namespaces

BurnsCommonVersion info and initialization

BurnsCommon.CoreLogger, DependencyChecker, UpdateChecker, ConfigHelper, KeybindManager, NotificationQueue, LocalizationManager

BurnsCommon.HelpersVehicleHelper, PedHelper, WorldHelper

BurnsCommon.CalloutsCalloutBase for LSPDFR callouts with auto-cleanup

BurnsCommon.AudioAudioHelper for WAV/MP3 playback

BurnsCommon.UIPopup dialog boxes with choices

Installation

For Users

1.Copy BurnsCommon.dll to your GTA V root folder (same location as GTA5.exe)
2.That's it — plugins that need it will automatically use it

For Plugin Developers

1.In Visual Studio: Right-click your project → Add → Reference
2.Browse to BurnsCommon.dll and click OK

Getting Started

After adding the reference, initialize BurnsCommon in your plugin's Initialize() method:

csharp

1using BurnsCommon;
2using BurnsCommon.Core;
3
4public class MyPlugin : Plugin
5{
6    public override void Initialize()
7    {
8        // Initialize BurnsCommon (logs that your plugin is using it)
9        BurnsCommonAPI.Initialize("MyPlugin");
10        
11        // Check dependencies before doing anything else
12        if (!DependencyChecker.Check(
13            pluginName: "MyPlugin",
14            minRphVersion: 1.98f,
15            minLspdfrVersion: new Version("0.4.9")))
16        {
17            // Dependencies not met - the checker already showed an error
18            return;
19        }
20        
21        // Your plugin code here...
22    }
23}

This is the recommended pattern: initialize, check dependencies, then proceed.

Logger

The Loggerclass provides consistent, prefixed log formatting. Create one with your plugin's name and use it throughout your code.

Namespace: BurnsCommon.Core

csharp

1using BurnsCommon.Core;
2
3// Create a logger with your plugin's prefix
4var log = new Logger("[MyPlugin]");
5
6log.Info("Plugin loaded successfully");
7log.Warning("Config value out of range, using default");
8log.Error("Failed to load file", exception);

Output in RagePluginHook.log:

text

[MyPlugin] Plugin loaded successfully
[MyPlugin] [WARN] Config value out of range, using default
[MyPlugin] [ERROR] Failed to load file

MethodDescription

Info(message)Log an informational message

Warning(message)Log a warning (prefixed with [WARN])

Error(message, exception?)Log an error with optional exception details

Dependency Checker

Validates that the required versions of RagePluginHook, LSPDFR, and any required files are present before your plugin runs. Shows the user a clear error notification if something is missing.

Namespace: BurnsCommon.Core

csharp

1using BurnsCommon.Core;
2
3bool success = DependencyChecker.Check(
4    pluginName: "MyPlugin",
5    minBurnsCommonVersion: new Version("1.0.0"),  // Optional
6    minRphVersion: 1.98f,                          // Optional
7    minLspdfrVersion: new Version("0.4.9"),        // Optional
8    requiredFiles: new[] {                         // Optional
9        "Plugins/LSPDFR/MyPlugin.ini",
10        "Plugins/LSPDFR/MyPlugin/sounds/alert.wav"
11    }
12);
13
14if (!success)
15{
16    // Error notification already shown to user
17    // Unload your plugin gracefully
18    return;
19}

MethodDescription

Check(pluginName, minBurnsCommonVersion?, minRphVersion?, minLspdfrVersion?, requiredFiles?)Validates all dependencies. Returns false if any check fails. Automatically displays error notifications to the user.

Update Checker

Checks a remote API for newer versions of your plugin and notifies the user if an update is available. Runs in the background so it doesn't block plugin loading.

Namespace: BurnsCommon.Core

csharp

1using BurnsCommon.Core;
2
3// In your Initialize() method:
4var updateChecker = new UpdateChecker(
5    pluginName: "MyPlugin",
6    currentVersion: "1.0.0",
7    apiUrl: "https://api.example.com/myplugin/version"
8);
9
10// Runs in background, shows notification if update available
11updateChecker.CheckAsync();

The API endpoint should return JSON like: {"version": "1.2.0"}

MethodDescription

UpdateChecker(pluginName, currentVersion, apiUrl)Create an update checker instance

CheckAsync()Asynchronously checks for updates and notifies the user if a new version is available

Config Helper

Utilities for reading INI configuration files with automatic value clamping. Prevents invalid config values from crashing your plugin.

Namespace: BurnsCommon.Core

csharp

1using BurnsCommon.Core;
2using Rage;
3
4string iniPath = ConfigHelper.GetIniPath("MyPlugin");
5// Returns: "Plugins/LSPDFR/MyPlugin.ini"
6
7var ini = new InitializationFile(iniPath);
8
9// Read with automatic clamping
10int scanRadius = ConfigHelper.ReadInt(ini, "Settings", "ScanRadius", 
11    defaultValue: 50, min: 10, max: 200);
12
13float volume = ConfigHelper.ReadFloat(ini, "Audio", "Volume",
14    defaultValue: 0.8f, min: 0f, max: 1f);

MethodDescription

GetIniPath(pluginName)Returns the standard INI path: "Plugins/LSPDFR/{pluginName}.ini"

ReadInt(ini, section, key, defaultValue, min, max)Reads an integer from INI, clamped between min and max

ReadFloat(ini, section, key, defaultValue, min, max)Reads a float from INI, clamped between min and max

Keybind Manager

Provides configurable keybinds with modifier key support. Keybinds can be set programmatically or loaded from an INI file so users can customize them.

Namespace: BurnsCommon.Core

csharp

1using BurnsCommon.Core;
2using System.Windows.Forms;
3
4// Create a keybind manager for your plugin
5var keybinds = new KeybindManager("MyPlugin");
6
7// Register keybinds with optional modifiers
8keybinds.Register("OpenMenu", Keys.F8);
9keybinds.Register("QuickAction", Keys.E, ModifierKeys.Ctrl);
10keybinds.Register("ToggleMode", Keys.T, ModifierKeys.Ctrl | ModifierKeys.Shift);
11
12// Load from INI file (overrides defaults with user config)
13var ini = new InitializationFile("Plugins/LSPDFR/MyPlugin.ini");
14keybinds.LoadFromIni(ini, section: "Keybinds");
15
16// Check in your main loop
17if (keybinds.IsPressed("OpenMenu"))
18{
19    // Key was just pressed this frame
20}
21
22if (keybinds.IsHeld("QuickAction"))
23{
24    // Key is currently held down
25}
26
27// Get display string for UI (e.g., "Ctrl+Shift+T")
28string display = keybinds.GetDisplayString("ToggleMode");
29Game.DisplayNotification($"Press ~b~{display}~s~ to toggle mode.");

INI file format:

ini

1[Keybinds]
2OpenMenu=F8
3OpenMenuCtrl=false
4OpenMenuShift=false
5OpenMenuAlt=false
6QuickAction=E
7QuickActionCtrl=true

MethodDescription

LoadFromIni(ini, section)Load user-customized keybinds from an INI file

IsPressed(name)Returns true if the key was just pressed this frame

IsHeld(name)Returns true if the key is currently held down

GetDisplayString(name)Returns a human-readable string like "Ctrl+Shift+T"

Notification Queue

Rate-limited GTA V notifications that prevent notification spam. Uses the standard GTA V notification system (same as other LSPDFR mods like Arrest Manager).

Namespace: BurnsCommon.Core

csharp

1using BurnsCommon.Core;
2
3// Create a notification queue (rate-limits to prevent spam)
4var notify = new NotificationQueue(minIntervalSeconds: 1.5f);
5
6// Simple notification
7notify.Show("~g~Suspect detained.");
8
9// With picture/icon (police department style)
10notify.Enqueue("~b~Dispatch", "~y~Traffic Stop", 
11    "Backup is en route.",
12    "web_lossantospolicedept", "web_lossantospolicedept");
13
14// Immediate notification (bypasses queue)
15notify.ShowImmediate("~b~Dispatch", "~y~Alert", "Officer needs assistance.",
16    "web_lossantospolicedept", "web_lossantospolicedept");
17
18// Clear pending notifications
19notify.Clear();

Common texture dictionaries for notification icons:

"web_lossantospolicedept"Police department logo

"mphud" / "mp_player_ready"Multiplayer ready icon

MethodDescription

NotificationQueue(minIntervalSeconds)Create a rate-limited notification queue

Show(message)Show a simple text notification

Enqueue(title, subtitle, message, txdDict, txdName)Queue a notification with a picture/icon

ShowImmediate(title, subtitle, message, txdDict, txdName)Show a notification immediately, bypassing the queue

Clear()Clear all pending notifications from the queue

Localization Manager

Multi-language support for plugins. Register strings with keys, add translations, and the manager handles language selection including auto-detection from the system locale.

Namespace: BurnsCommon.Core

csharp

1using BurnsCommon.Core;
2
3// Create and register default (English) strings
4var lang = new LocalizationManager("MyPlugin");
5lang.Register("greeting", "Welcome, Officer.");
6lang.Register("suspect_fled", "The suspect has fled the scene.");
7lang.Register("backup_eta", "Backup arriving in {0} seconds.");
8
9// Add translations
10lang.AddTranslation("de", "greeting", "Willkommen, Officer.");
11lang.AddTranslation("de", "suspect_fled", "Der Verdaechtige ist geflohen.");
12lang.AddTranslation("es", "greeting", "Bienvenido, Oficial.");
13
14// Or load translations from an INI file
15lang.LoadFromIni("Plugins/LSPDFR/MyPlugin/lang.ini");
16
17// Auto-detect system language
18lang.AutoDetectLanguage();
19
20// Or set manually
21lang.CurrentLanguage = "de";
22
23// Use translations
24Game.DisplayNotification(lang.Get("greeting"));
25Game.DisplayNotification(lang["suspect_fled"]); // Shorthand
26Game.DisplayNotification(lang.GetFormatted("backup_eta", 30));
27
28// Check available languages
29string[] available = lang.GetAvailableLanguages();

Language INI file format:

ini

1[en]
2greeting=Welcome, Officer.
3suspect_fled=The suspect has fled the scene.
4
5[de]
6greeting=Willkommen, Officer.
7suspect_fled=Der Verdaechtige ist geflohen.
8
9[es]
10greeting=Bienvenido, Oficial.

MethodDescription

AddTranslation(languageCode, key, text)Add a translation for a specific language

LoadFromIni(path)Load all translations from an INI file

AutoDetectLanguage()Set language based on system locale

Get(key) / this[key]Get the translated string for the current language

GetFormatted(key, args)Get a translated string with format arguments

GetAvailableLanguages()Returns an array of available language codes

Vehicle Helper

Utility methods for working with GTA V vehicles: classification, police/emergency checks, occupant queries, and spawn helpers.

Namespace: BurnsCommon.Helpers

csharp

1using BurnsCommon.Helpers;
2
3// Check vehicle type
4VehicleClass vClass = VehicleHelper.GetVehicleClass(vehicle);
5bool isPolice = VehicleHelper.IsPoliceVehicle(vehicle);
6bool isEmergency = VehicleHelper.IsEmergencyVehicle(vehicle);
7bool isBike = VehicleHelper.IsTwoWheeler(vehicle);
8bool isStolen = VehicleHelper.IsStolen(vehicle);
9
10// Get player's current vehicle (null if on foot)
11Vehicle playerCar = VehicleHelper.GetPlayerVehicle();
12
13// Get nearby vehicles
14Vehicle[] nearby = VehicleHelper.GetNearbyVehicles(
15    Game.LocalPlayer.Character.Position, 50f);
16
17// Check occupants
18bool hasDriver = VehicleHelper.HasDriver(vehicle);
19Ped[] occupants = VehicleHelper.GetOccupants(vehicle);
20
21// Utility
22VehicleHelper.MakePersistent(vehicle);
23VehicleHelper.RepairAndClean(vehicle);

MethodDescription

GetVehicleClass(vehicle)Returns the vehicle class enum

IsPoliceVehicle(vehicle)Returns true if the vehicle is a police vehicle

IsEmergencyVehicle(vehicle)Returns true if the vehicle is an emergency vehicle

IsTwoWheeler(vehicle)Returns true if the vehicle is a motorcycle or bicycle

IsStolen(vehicle)Returns true if the vehicle is flagged as stolen

GetPlayerVehicle()Returns the player's current vehicle, or null if on foot

GetNearbyVehicles(position, radius)Returns all vehicles within the given radius

HasDriver(vehicle)Returns true if the vehicle has a driver

GetOccupants(vehicle)Returns an array of all peds in the vehicle

MakePersistent(vehicle)Prevents the vehicle from being despawned by the game

RepairAndClean(vehicle)Fully repairs and cleans the vehicle

Ped Helper

Utility methods for working with GTA V peds (characters): weapon checks, status queries, proximity searches, and action commands.

Namespace: BurnsCommon.Helpers

csharp

1using BurnsCommon.Helpers;
2
3// Weapon checks
4bool armed = PedHelper.IsArmed(suspect);
5bool hasGun = PedHelper.HasFirearm(suspect);
6
7// Status checks
8bool isCop = PedHelper.IsCop(ped);
9bool isDead = PedHelper.IsDead(ped);
10bool inCar = PedHelper.IsInVehicle(ped);
11bool wanted = PedHelper.IsWanted(Game.LocalPlayer.Character);
12
13// Get ped's vehicle (null if on foot)
14Vehicle car = PedHelper.GetVehicle(suspect);
15
16// Find peds nearby
17Ped[] nearbyPeds = PedHelper.GetNearbyPeds(position, 100f, excludePlayer: true);
18Ped closest = PedHelper.GetClosestPed(position, maxRadius: 50f);
19
20// Actions
21PedHelper.Flee(suspect, Game.LocalPlayer.Character.Position);
22PedHelper.Surrender(suspect);
23PedHelper.GiveWeapon(suspect, "WEAPON_PISTOL", ammo: 50, equip: true);
24PedHelper.MakePersistent(suspect);

MethodDescription

IsArmed(ped)Returns true if the ped has any weapon

HasFirearm(ped)Returns true if the ped has a firearm specifically

IsCop(ped)Returns true if the ped is law enforcement

IsDead(ped)Returns true if the ped is dead

IsInVehicle(ped)Returns true if the ped is inside a vehicle

IsWanted(ped)Returns true if the ped has a wanted level

GetVehicle(ped)Returns the ped's current vehicle, or null if on foot

GetNearbyPeds(position, radius, excludePlayer?)Returns all peds within the given radius

GetClosestPed(position, maxRadius)Returns the closest ped within the radius

Flee(ped, fromPosition)Makes the ped run away from the given position

Surrender(ped)Makes the ped put their hands up

GiveWeapon(ped, weaponName, ammo, equip?)Gives the ped a weapon with specified ammo

MakePersistent(ped)Prevents the ped from being despawned by the game

World Helper

Utility methods for the game world: location info, safe spawn points, terrain checks, distance calculations, and time queries.

Namespace: BurnsCommon.Helpers

csharp

1using BurnsCommon.Helpers;
2
3// Player position shortcut
4Vector3 playerPos = WorldHelper.PlayerPosition;
5
6// Location info
7string zone = WorldHelper.GetZoneName(position);
8string street = WorldHelper.GetStreetName(position);
9
10// Spawn points
11Vector3 safeSpawn = WorldHelper.GetSafeSpawnPoint(
12    playerPos, minDistance: 20f, maxDistance: 50f);
13Vector3 roadSpawn = WorldHelper.GetRandomRoadPosition(playerPos, radius: 100f);
14
15// Terrain checks
16float groundZ = WorldHelper.GetGroundZ(position);
17bool onRoad = WorldHelper.IsPositionOnRoad(position);
18bool inWater = WorldHelper.IsPositionInWater(position);
19
20// Utility
21float dist = WorldHelper.GetDistance(pos1, pos2);
22float heading = WorldHelper.GetHeadingTowards(from, to);
23bool isNight = WorldHelper.IsNightTime();
24string gameTime = WorldHelper.GetGameTimeString(); // "14:30"
25
26// Create a blip
27Blip blip = WorldHelper.CreateBlip(
28    position, color: Color.Red, name: "Suspect");

MethodDescription

PlayerPositionShortcut to get the player's current position

GetZoneName(position)Returns the zone/area name at the position

GetStreetName(position)Returns the street name at the position

GetSafeSpawnPoint(position, minDistance, maxDistance)Finds a safe spawn point on a road within the given range

GetRandomRoadPosition(position, radius)Returns a random position on a road nearby

GetGroundZ(position)Returns the ground height at the given position

IsPositionOnRoad(position)Returns true if the position is on a road

IsPositionInWater(position)Returns true if the position is in water

GetDistance(pos1, pos2)Returns the distance between two positions

GetHeadingTowards(from, to)Returns the heading angle from one position to another

IsNightTime()Returns true if it's night in the game world

GetGameTimeString()Returns the in-game time as a string like "14:30"

CreateBlip(position, color, name)Creates a named blip on the map at the given position

Callout Base

A base class for LSPDFR callouts that provides automatic entity cleanup, error handling, and logging. Inherit from CalloutBase instead of the standard LSPDFR Callout class.

Namespace: BurnsCommon.Callouts

csharp

1using BurnsCommon.Callouts;
2using Rage;
3using LSPD_First_Response.Mod.Callouts;
4using System.Drawing;
5
6[CalloutInfo("Robbery In Progress", CalloutProbability.Medium)]
7public class RobberyCallout : CalloutBase
8{
9    private Ped _suspect;
10    private Vehicle _suspectVehicle;
11    private Blip _suspectBlip;
12
13    // Required: display name for logs and dispatch
14    protected override string CalloutName => "Robbery In Progress";
15
16    // Required: set up spawn point, return true to show callout
17    protected override bool Setup()
18    {
19        CalloutPosition = WorldHelper.GetSafeSpawnPoint(
20            WorldHelper.PlayerPosition, 100f, 250f);
21        CalloutMessage = "Robbery In Progress";
22        return true;
23    }
24
25    // Required: spawn entities when player accepts
26    protected override void OnAccepted()
27    {
28        // SpawnPed/SpawnVehicle auto-register for cleanup
29        _suspect = SpawnPed("a_m_y_stbla_02", CalloutPosition);
30        _suspectVehicle = SpawnVehicle("sultan", CalloutPosition);
31
32        // CreateBlip auto-registers for cleanup
33        _suspectBlip = CreateBlip(_suspect, Color.Red, "Suspect");
34
35        PedHelper.GiveWeapon(_suspect, "WEAPON_PISTOL");
36
37        ShowDispatch("Reports of a robbery. Suspect is armed.");
38    }
39
40    // Required: runs every tick while callout is active
41    protected override void OnProcess()
42    {
43        if (PedHelper.IsDead(_suspect))
44        {
45            ShowDispatch("Suspect is down. Code 4.");
46            EndCallout();
47        }
48    }
49
50    // Optional: extra cleanup logic
51    protected override void OnCleanup()
52    {
53        Log.Info("Robbery callout cleaned up");
54    }
55}

Key benefits of CalloutBase

•Auto-cleanup — All entities/blips registered via SpawnPed(), SpawnVehicle(), CreateBlip() are automatically dismissed when the callout ends
•Error handling — Exceptions in OnProcess() are caught and logged instead of crashing
•Built-in logger — Log.Info(), Log.Warning(), Log.Error() available in every callout
•Dispatch helper— ShowDispatch("message") sends a formatted police dispatch notification

MethodDescription

CalloutName (override)Set the display name for logs and dispatch

Setup() (override)Set spawn point and callout message. Return true to show callout.

OnAccepted() (override)Spawn entities and set up the callout scene

OnProcess() (override)Called every tick while the callout is active

OnCleanup() (override)Optional extra cleanup logic when callout ends

SpawnPed(model, position)Spawns a ped and registers it for automatic cleanup

SpawnVehicle(model, position)Spawns a vehicle and registers it for automatic cleanup

CreateBlip(entity, color, name)Creates a blip and registers it for automatic cleanup

ShowDispatch(message)Sends a formatted police dispatch notification

EndCallout()Ends the callout and triggers cleanup

Audio Helper

Play WAV and MP3 audio files asynchronously in your plugin. Useful for custom sound effects, radio chatter, or alerts.

Namespace: BurnsCommon.Audio

csharp

1using BurnsCommon.Audio;
2
3// Play a WAV file
4AudioHelper.PlayAsync(
5    "Plugins/LSPDFR/MyPlugin/sounds/alert.wav", "[MyPlugin]");
6
7// Play an MP3 file
8AudioHelper.PlayAsync(
9    "Plugins/LSPDFR/MyPlugin/sounds/music.mp3", "[MyPlugin]");
10
11// Stop all sounds
12AudioHelper.StopAll();

MethodDescription

PlayAsync(filePath, logPrefix)Plays an audio file (WAV or MP3) asynchronously in the background

StopAll()Stops all currently playing audio

Popup Dialogs

In-game dialog boxes with support for simple messages, yes/no confirmations, and multiple choice selection.

Namespace: BurnsCommon.UI

csharp

1using BurnsCommon.UI;
2
3// Simple message
4Popup.Message("Notice", "The suspect has been detained.");
5
6// Yes/No confirmation
7Popup.Confirm("Pursuit", "Call for backup?",
8    onYes: () => Game.LogTrivial("Backup requested"),
9    onNo: () => Game.LogTrivial("Going solo")
10);
11
12// Multiple choice
13var popup = new Popup(
14    title: "Select Action",
15    text: "What would you like to do?",
16    answers: new List<string> { "Arrest", "Release", "Question" },
17    pauseGame: false,
18    callback: p => {
19        switch (p.IndexOfGivenAnswer)
20        {
21            case 0: /* Arrest */ break;
22            case 1: /* Release */ break;
23            case 2: /* Question */ break;
24        }
25    }
26);
27popup.Display();

MethodDescription

Popup.Message(title, text)Shows a simple informational dialog

Popup.Confirm(title, text, onYes, onNo)Shows a yes/no confirmation dialog with callbacks

new Popup(title, text, answers, pauseGame, callback)Creates a multiple-choice dialog with a callback for the selected answer

Display()Shows the popup dialog to the player

Complete Example Plugin

Here's a complete example showing how to set up a plugin that uses BurnsCommon for initialization, dependency checking, update checking, and logging:

csharp

1using System;
2using Rage;
3using BurnsCommon;
4using BurnsCommon.Core;
5
6[assembly: Rage.Attributes.Plugin("ExamplePlugin", 
7    Description = "Example using BurnsCommon")]
8
9public class ExamplePlugin : Plugin
10{
11    private Logger _log;
12
13    public override void Initialize()
14    {
15        _log = new Logger("[ExamplePlugin]");
16        
17        // Initialize BurnsCommon
18        BurnsCommonAPI.Initialize("ExamplePlugin");
19        
20        // Check dependencies
21        if (!DependencyChecker.Check("ExamplePlugin", 
22            minRphVersion: 1.98f))
23        {
24            _log.Error("Dependencies not met, unloading");
25            return;
26        }
27        
28        // Check for updates
29        new UpdateChecker("ExamplePlugin", "1.0.0", 
30            "https://api.example.com/version").CheckAsync();
31        
32        _log.Info("Plugin loaded successfully");
33        Game.DisplayNotification(
34            "~g~ExamplePlugin~s~ loaded successfully!");
35    }
36
37    public override void Finally()
38    {
39        _log.Info("Plugin unloaded");
40    }
41}

Distribution

When distributing your plugin that depends on BurnsCommon:

1.Include BurnsCommon.dll with your plugin download, OR
2.Tell users to install BurnsCommon separately from the download page
3.The DependencyChecker will warn users if BurnsCommon is missing or outdated

BurnsCommon Documentation

On this page

Overview

Namespaces

Installation

For Users

For Plugin Developers

Getting Started

Logger

Dependency Checker

Update Checker

Config Helper

Keybind Manager

Notification Queue

Localization Manager

Vehicle Helper

Ped Helper

World Helper

Callout Base

Key benefits of CalloutBase

Audio Helper

Popup Dialogs

Complete Example Plugin

Distribution