fivem-rpc/rpc/readme.md

FiveM RPC

is an all-in package with asynchronous RPC implementation for RageMP servers in JS/TS. Extra info

Motivation

The idea was to create an extensible package, with various features to simplify the development process and provide as much comfort as possible. Inspired by usage of altv-xrpc

Installation

  pnpm i @entityseven/fivem-rpc

  yarn add @entityseven/fivem-rpc

  bun add @entityseven/fivem-rpc

It is highly recommended to also install additional package for enhanced typing

  pnpm i @entityseven/fivem-rpc-shared-types -D

  yarn add @entityseven/fivem-rpc-shared-types --dev

  bun add @entityseven/fivem-rpc-shared-types -d

Usage

FiveM RPC is meant to be a singletone per environment. This means you must create only one RPCFactory per your server/client/web. This also enables modifying const rpc to your needs, adding new methods or variables by forcing you to import it from file instead of library reference

// lib/rpc.ts
import { RPCFactory } from '@entityseven/fivem-rpc'
export const rpc = new RPCFactory(/* options */).get()

Docs

Extras

Along with RPCFactory you can also import all the types used internally, types for native client/server events and lists of native client/server events. All of that is documented in JSDoc, so no need to duplicate it here

RPCConfig

type RPCConfig<T extends RPCEnvironment | unknown> = {
    env: T 
    debug?: boolean
}

Failing to set env to provided type will result in RPCErrors.UNKNOWN_ENVIRONMENT debug adds additional console logs to events

Errors

Known errors could be one of following or an error throw by a callback specifically

enum RPCErrors {
    EVENT_NOT_REGISTERED = 'Event not registered',
    INVALID_DATA = 'Invalid data (possibly broken JSON)',
    NO_PLAYER = 'No player (failed to resolve from local index)',
    UNKNOWN_NATIVE = 'Unknown native event (if you are sure this exists - use native handler)',
    UNKNOWN_ENVIRONMENT = 'Unknown environment (must be either "server", "client" or "webview")',
}

Example error

Values wrapped in <> always exist, just not relevant for an example. Keep in mind that some errors are thrown in their destination(To) point: this example will throw on server

Error: No player (failed to resolve from local index)
Event: 'clientServerEvent'
Uuid: <uuid>
From: 'client'
To: 'server'
Player: <non-existent-player>
Type: 'event'
Data: [<data>]

Server (source)

onClient

Listens to client event

rpc.onClient('clientServerEvent', (player, arg1, arg2, ...rest) => {
    // logic
    return someData // this will be forwarded back to caller
})

offClient

Stops listening to client event

rpc.offClient('clientServerEvent')

emitClient

Sends event to specified client

const response = await rpc.emitClient(playerServerId, 'serverClientEvent', someData) 
// response will come from client listener with returned data

emitClientEveryone

Sends event to all clients

rpc.emitClientEveryone('serverClientEvent', someData)

onWebview

Listens to webview event

rpc.onWebview('webviewServerEvent', (player, arg1, arg2, ...rest) => {
    // logic
    return someData // this will be forwarded back to caller
})

offWebview

Stops listening to webview event

rpc.offWebview('webviewServerEvent')

emitWebview

Sends event to specified webview

const response = await rpc.emitWebview(playerServerId, 'serverWebviewEvent', someData)
// response will come from webview listener with returned data

onSelf

Listens to server event

rpc.onSelf('serverEvent', (arg1, arg2, ...rest) => {
    // logic 
    return someData // this will be forwarded back to caller
})

offSelf

Stops listening to server event

rpc.offSelf('serverEvent')

emitSelf

Sends event to server

const response = await rpc.emitSelf('serverEvent', someData)
// response will come from server listener with returned data

onCommand

Registers chat command. Since arguments are untyped you must validate them yourself

rpc.onCommand('serverCommand', (player, args, commandRaw) => {
    // logic
})

onNativeEvent

Listens to native server event (reference)

rpc.onNativeEvent('playerJoining', (source, oldId) => {
    // logic
})

Client (source)

onServer

Listens to server event

rpc.onServer('serverClientEvent', (arg1, arg2, ...rest) => {
    // logic
    return someData // this will be forwarded back to caller
})

offServer

Stops listening to server event

rpc.offServer('serverClientEvent')

emitServer

Sends event to server

const response = await rpc.emitServer('clientServerEvent', someData)
// response will come from webview listener with returned data

onWebview

Listens to webview event

rpc.onWebview('webviewClientEvent', (arg1, arg2, ...rest) => {
    // logic
    return someData // this will be forwarded back to caller
})

offWebview

Stops listening to webview event

rpc.offWebview('webviewClientEvent')

emitWebview

Sends event to specified webview

const response = await rpc.emitWebview('clientWebviewEvent', someData)
// response will come from webview listener with returned data

onSelf

Listens to client event

rpc.onSelf('clientEvent', (arg1, arg2, ...rest) => {
    // logic 
    return someData // this will be forwarded back to caller
})

offSelf

Stops listening to client event

rpc.offSelf('clientEvent')

emitSelf

Sends event to client

const response = await rpc.emitSelf('clientEvent', someData)
// response will come from client listener with returned data

onCommand

Registers chat command. Since arguments are untyped you must validate them yourself

rpc.onCommand('clientCommand', (player, args, commandRaw) => {
    // logic
})

onNativeEvent

Listens to native client event (reference)

rpc.onNativeEvent('entityDamaged', (victim, culprit, weapon, baseDamage) => {
    // logic
})

onNativeNetworkEvent

Listens to native client network event (reference)

rpc.onNativeNetworkEvent('CEventShockingCarCrash', (entities, eventEntity, data) => {
    // logic
})

setWebviewFocus

Sets or removes focus and cursor from own webview

rpc.setWebviewFocus(true /* focus */, true /* show cursor */)

Webview (source)

onClient

Listens to client event

rpc.onClient('clientWebviewEvent', (arg1, arg2, ...rest) => {
    // logic
    return someData // this will be forwarded back to caller
})

offClient

Stops listening to client event

rpc.offClient('clientWebviewEvent')

emitClient

Sends event to own client

const response = await rpc.emitClient('webviewClientEvent', someData) 
// response will come from client listener with returned data

onServer

Listens to server event

rpc.onServer('serverWebviewEvent', (arg1, arg2, ...rest) => {
    // logic
    return someData // this will be forwarded back to caller
})

offServer

Stops listening to server event

rpc.offServer('serverWebviewEvent')

emitServer

Sends event to server

const response = await rpc.emitServer('webviewServerEvent', someData)
// response will come from webview listener with returned data

onSelf

Listens to webview event

rpc.onSelf('webviewEvent', (arg1, arg2, ...rest) => {
    // logic 
    return someData // this will be forwarded back to caller
})

offSelf

Stops listening to webview event

rpc.offSelf('webviewEvent')

emitSelf

Sends event to webview

const response = await rpc.emitSelf('webviewEvent', someData)
// response will come from webview listener with returned data

License

Licensed under Custom Attribution-NoDerivs Software License