Custom RPC

Exchange your own binary packets between a client mod and the server.

SA-MP leaves a large part of the RPC id space unused. Knight lets a gamemode claim those ids and exchange its own binary payloads with a modified client. The engine validates the frame, enforces a size limit and a per-player rate limit, then hands the payload to your handler.

1. Register a handler

function onInventoryRPC(RPC rpc) {
    let item = rpc.reader.read_int32();
    let amount = rpc.reader.read_int32();

    if (!rpc.reader.valid()) { return; }   // truncated payload

    SendCustomRPC(rpc.playerid, 201, RPCPack("u32", item, "u32", amount));
};

system::start() {
    HandleCustomRPC(200, onInventoryRPC, {
        direction: "incoming",
        max_size: 4096,
        rate_limit: 20,
        client_mod: true
    });
};

2. Options

3. The RPC object

4. Reader methods

5. Building payloads

RPCPack assembles little-endian fields so the client mod can parse them:

let payload = RPCPack("u8", 7, "u16", 300, "u32", 70000, "f32", 1.5, "s", "hi");
SendCustomRPC(playerid, 201, payload);          // one player
SendCustomRPC(-1, 201, payload);               // everyone (broadcast)

6. Which clients may send it

With client_mod: true, only clients that append +knight-rpc to the version string in their ClientJoin are accepted. Everything else is silently ignored, so a stock 0.3.7 client can never trigger the handler.

ClientJoin version string: 0.3.7+knight-rpc

The bundled knight-client advertises it by default (-clientmod) and can send a test packet:

./knight-client -host 127.0.0.1 -port 7777 -name RPCBot     -customrpc 200 -rpc1 42 -rpc2 8

7. Helpers

8. Security model

• The frame is parsed by the engine; a malformed RPC frame is dropped before your handler.
• Payloads larger than max_size never reach the handler.
• The rate limit is per player and per id, counted in one-second buckets.
• The reader cannot read past the payload and never panics.
• Stock RPC ids cannot be hijacked.

9. Multiple handlers: HandleRPC

HandleCustomRPC installs one handler per id. HandleRPC installs many: each has a priority and an optional payload filter, they run from highest priority down, and the first one that matches consumes the packet. If none matches, the packet is ignored.

HandleRPC(230, onFallback, { priority: 1, max_size: 4096, rate_limit: 20 });
HandleRPC(230, onExact, {
    priority: 50,
    direction: "incoming",
    filter: { match: "prefix", bytes: "AA" }
});

Handlers and HandleCustomRPC coexist: the engine tries the HandleRPC chain first, then falls back to the HandleCustomRPC handler for the same id.

10. Payload filters

offset (default 0) and length (default: to the end) select the window before matching. Out-of-range values never match and never crash.

// payload: AA 00 05
CheckRPC(230, payload, { match: "prefix", bytes: "AA" });                  // true
CheckRPC(230, payload, { match: "exact", bytes: "AA", length: 2 });        // true
CheckRPC(230, payload, { match: "contains", bytes: "{0x05}" });        // true
CheckRPC(230, payload, { match: "exact", bytes: "AA", offset: 2 });        // false

11. CheckRPC

CheckRPC(id, payload, options) is a pure predicate: it registers nothing and returns whether an id and payload match your criteria. Useful inside a handler to route on a header, or before sending a reply.

system::start() {
    let probe = RPCPack("u8", 65, "u8", 65, "u8", 1);
    Log("prefix={CheckRPC(230, probe, { match: "prefix", bytes: "AA" })}");
    Log("contains={CheckRPC(230, probe, { match: "contains", bytes: "A" })}");
    Log("offset={CheckRPC(230, probe, { match: "exact", bytes: "AA", length: 2 })}");
};

12. Managing handlers