Amnesty.RageMp 1.0.3

Amnesty.RageMp

Official C# SDK for Amnesty — collect and audit game events from your multiplayer server.

Overview

The SDK sends events to the Amnesty collector in the background — fire-and-forget, non-blocking. It handles authentication, queuing, and retries automatically so your game logic is never affected.

Two modes are available:

Requirements

• .NET Core 3.1 or .NET 8.0
• A running Amnesty instance
• A service account with access to your project (created in the web panel under Users)

Installation

dotnet add package Amnesty.RageMp

Quick Start

Templates mode

Call Configure() once at server startup, then call Track*() at key points in your code.

using Amnesty.RageMp;

// In your resource constructor (after RAGE:MP assemblies are loaded)
Amnesty.Configure(new AmnestyOptions
{
    ApiUrl    = "https://amnesty.example.com",
    ProjectId = "gta5-ragemp-roleplay",
    Username  = "gameserver",
    Password  = "secret",
});

// Single-step event
Amnesty.TrackSuccess("player_login",
    playerId: player.SocialClubName,
    appName:  "server",
    payload:  new Dictionary<string, object>
    {
        ["playerName"] = player.Name,
        ["ip"]         = player.Address,
    });

// Multi-step operation (Start → Success / Fail)
var trace = Amnesty.NewTraceId();

Amnesty.TrackStart("vehicle_purchase", trace,
    playerId: player.SocialClubName, appName: "server");

if (success)
    Amnesty.TrackSuccess("vehicle_purchase", trace,
        playerId: player.SocialClubName, appName: "server",
        payload: new Dictionary<string, object> { ["model"] = carModel, ["price"] = price });
else
    Amnesty.TrackFail("vehicle_purchase", trace,
        playerId: player.SocialClubName, appName: "server",
        payload: new Dictionary<string, object> { ["reason"] = "insufficient_funds" });

Raw mode

Set AutoTrack = true — the SDK intercepts every TriggerClientEvent call via Harmony and forwards it to the collector automatically. No templates or manual Track() calls needed.

using Amnesty.RageMp;

Amnesty.Configure(new AmnestyOptions
{
    ApiUrl    = "https://amnesty.example.com",
    ProjectId = "gta5-ragemp-roleplay",
    Username  = "gameserver",
    Password  = "secret",
    AutoTrack = true,
});

Using gRPC transport

By default, the SDK uses HTTP REST. For high-RPS servers, switch to gRPC for lower latency and binary encoding:

using Amnesty.RageMp;

Amnesty.Configure(new AmnestyOptions
{
    ApiUrl    = "https://amnesty.example.com",
    ProjectId = "gta5-ragemp-roleplay",
    Username  = "gameserver",
    Password  = "secret",
    Transport = TransportMode.Grpc,
    GrpcUrl   = "https://amnesty.example.com:9090",
});

On .NET Core 3.1 with an http:// (plaintext) gRPC endpoint, set the following before calling Configure():

AppContext.SetSwitch("System.Net.Http.SocketsHttpHandler.Http2UnencryptedSupport", true);

The SDK sets this automatically when it detects http:// on .NET Core 3.1.

Configuration reference

API reference

Amnesty.Configure(options)

Initialises the SDK. Call once at server startup, inside your resource constructor (not in a static initializer — RAGE:MP assemblies must be loaded first).

Amnesty.Track(templateName, status, ...)

Enqueues an event. Never throws. Never blocks.

Shortcuts

Amnesty.TrackStart(templateName, traceId?, playerId?, appName?, payload?)
Amnesty.TrackSuccess(templateName, traceId?, playerId?, appName?, payload?)
Amnesty.TrackFail(templateName, traceId?, playerId?, appName?, payload?)

Amnesty.NewTraceId()  // returns a UUID string

Integration example (standard RAGE:MP resource)

// dotnet/resources/YourResource/Main.cs
using Amnesty.RageMp;

public class Main : Script
{
    public Main()
    {
        Amnesty.Configure(new AmnestyOptions
        {
            ApiUrl    = Environment.GetEnvironmentVariable("AMNESTY_API_URL")    ?? "http://localhost:3000",
            ProjectId = Environment.GetEnvironmentVariable("AMNESTY_PROJECT_ID") ?? "my-server",
            Username  = Environment.GetEnvironmentVariable("AMNESTY_USERNAME")   ?? "gameserver",
            Password  = Environment.GetEnvironmentVariable("AMNESTY_PASSWORD")   ?? "secret",
            AutoTrack = true,
        });
    }
}

Store credentials in a .env file or environment variables — never hardcode them in source.

License

MIT