From c4ef099b6182c30194086b2926509d0f4475c1a1 Mon Sep 17 00:00:00 2001 From: rilaxik Date: Wed, 30 Oct 2024 15:27:00 +0000 Subject: [PATCH] updated descriptions --- Docs%400.2.0.md | 323 +++++++++++++++++++++++++++++++++++------------- 1 file changed, 236 insertions(+), 87 deletions(-) diff --git a/Docs%400.2.0.md b/Docs%400.2.0.md index 3070c83..628a215 100644 --- a/Docs%400.2.0.md +++ b/Docs%400.2.0.md @@ -29,16 +29,16 @@ return true /*Promise*/ }) ``` -## Server +# Server Package used on a server-side of your Rage:MP Server -### Usage +## Usage ```ts import { fw } from '@entityseven/rage-fw-server' ``` Only usable in server environment. For usage in [Client](#client) and [Browser](#browser) refer to their sections -### Declaration +## Declaration ```ts fw = { event: Server, @@ -51,78 +51,105 @@ fw = { ``` Further documentation will describe the fields included in ``fw`` -### Server -Handles event manipulations that do not require player to be present in context +## Server +Server-side interactions -#### register -Registers server event +### register +Registers a server event with an associated callback ```ts -fw.event.register('serverEventName', ([arg1, arg2]) => { - // your logic here +fw.event.register("playerJoin", (player) => { + // do something +}) + +// Registering an event with middlewares +fw.event.register("playerJoin", (player) => { + // do something +}, { + middlewares: [...] // <- your middlewares here +}) + +// or + +fw.event.register("playerJoin", (player) => { + // do something +}, { + middlewares: { + executables: [...], // <- your middlewares here + onError: (msg) => void msg // <- error handling here + } }) ``` -#### unregister -Unregisters server event +### unregister +Unregisters a server event, removing the associated callback ```ts -fw.event.unregister('serverEventName') +fw.event.unregister("playerJoin") ``` -#### trigger +### trigger Triggers registered server event. Formerly known as ``call`` or ``emit`` ```ts fw.event.trigger('serverEventName', ['arg1', 2]) ``` -### Player +## Player Handles event manipulations that require player to be present in context -#### triggerClient -Triggers registered client event with passed arguments. Formerly known as ``callClient`` or ``emitClient`` +### triggerClient +Triggers a client event from the server with arguments from shared types. Formerly known as ``callClient`` or ``emitClient`` ```ts -fw.player.triggerClient('clientEventName', ['arg1', 2]) +// without args +fw.player.triggerClient("clientEventName") +// with args +fw.player.triggerClient("clientEventName", ["message to client"]) ``` -#### triggerBrowser -Triggers registered CEF event with passed arguments. Formerly known as ``callBrowser`` or ``emitBrowser`` +### triggerBrowser +Triggers a browser event from the server with arguments from shared types. Formerly known as ``callBrowser`` or ``emitBrowser`` ```ts -fw.player.triggerBrowser('cefEventName', ['arg1', 2]) +// without args +fw.player.triggerBrowser("browserEventName") +// with args +fw.player.triggerBrowser("browserEventName", ["message to browser"]) ``` -### System +## System Handles functions used to interact with system environment -#### Logger -Used to log in a server console +### Logger +Used to log to a client in-game console -##### info +#### info Informational logs. Colored in white ```ts fw.system.log.info('some information to be logged') ``` -##### warn +#### warn Warning logs. Colored in yellow ```ts -fw.system.log.info('warning message') +fw.system.log.warn('warning message') ``` -##### error +#### error Error logs. Colored in red ```ts -fw.system.log.info('error message') +fw.system.log.info('some error information') ``` -## Client +## Rpc +``rage-fw-rpc`` instance used under the hood. It is highly recommended to use this one if you need it instead of creating a new instance + +# Client Package used on a client-side of your Rage:MP Server -### Usage +## Usage ```ts import { fw } from '@entityseven/rage-fw-client' ``` Only usable in client environment. For usage in [Server](#server) and [Browser](#browser) refer to their docs -### Declaration +## Declaration ```ts fw = { event: Client, @@ -135,86 +162,114 @@ fw = { ``` Further documentation will describe the fields included in ``fw`` -### Client -Handles event manipulations that do not require player to be present in context +## Client +Client-side interactions -#### register -Registers client event +### register +Registers a client event with an associated callback ```ts -fw.event.register('clientEventName', ([arg1, arg2]) => { - // your logic here +fw.event.register("playerDeath", (player, reason, killer) => { + // do something +}) + +// Registering an event with middlewares +fw.event.register("playerDeath", (player, reason, killer) => { + // do something +}, { + middlewares: [...] // <- your middlewares here +}) + +// or + +fw.event.register("playerDeath", (player, reason, killer) => { + // do something +}, { + middlewares: { + executables: [...], // <- your middlewares here + onError: (msg) => void msg // <- error handling here + } }) ``` -#### unregister -Unregisters client event +### unregister +Unregisters a client event, removing the associated callback ```ts -fw.event.unregister('clientEventName') +fw.event.unregister("playerDeath") ``` -### Player +## Player Handles event manipulations that require player to be present in context -#### trigger +### browser +Setter. Also shares browser with ``rage-fw-rpc`` +```ts +fw.player.browser = mp.browsers.new('package://index.html') +``` + +### trigger Triggers registered client event with passed arguments. Formerly known as ``call`` or ``emit`` ```ts -fw.player.trigger('clientEventName', ['arg1', 2]) +// without args +fw.player.trigger("clientEventName") +// with args +fw.player.trigger("clientEventName", ["message to me"]) ``` -#### triggerServer -Triggers registered client event with passed arguments. Formerly known as ``callServer`` or ``emitServer`` +### triggerServer +Triggers a server event from the client with arguments from shared types. Formerly known as ``callServer`` or ``emitServer`` ```ts -fw.player.triggerServer('serverEventName', ['arg1', 2]) +// without args +fw.player.triggerServer("serverEventName") +// with args +fw.player.triggerServer("serverEventName", ["message to server"]) ``` -#### triggerBrowser -Triggers registered CEF event with passed arguments. Formerly known as ``callBrowser`` or ``emitBrowser`` +### triggerBrowser +Triggers a browser event from the client with arguments from shared types. Formerly known as ``callBrowser`` or ``emitBrowser`` ```ts -fw.player.triggerBrowser('cefEventName', ['arg1', 2]) +// without args +fw.player.triggerBrowser("browserEventName") +// with args +fw.player.triggerBrowser("browserEventName", ["message to browser"]) ``` -### Browser +## System +Handles functions used to interact with the client environment -#### registerBrowser -Used to assign a browser instance. Returns the same browser instance -```ts -fw.browser.registerBrowser(browserInstance) -``` +### Logger +Used to log to a client in-game console -### System -Handles functions used to interact with system environment - -#### Logger -Used to log in a client in-game console - -##### info +#### info Informational logs. Colored in white ```ts fw.system.log.info('some information to be logged') ``` -##### warn +#### warn Warning logs. Colored in yellow ```ts -fw.system.log.info('warning message') +fw.system.log.warn('warning message') ``` -##### error +#### error Error logs. Colored in red ```ts -fw.system.log.info('error message') +fw.system.log.info('some error information') ``` -## Browser +## Rpc +``rage-fw-rpc`` instance used under the hood. It is highly recommended to use this one if you need it instead of creating a new instance + +# Browser Package used on a browser-side of your Rage:MP Server -### Usage +## Usage ```ts import { fw } from '@entityseven/rage-fw-browser' ``` -Only usable in CEF environment. For usage in [Server](#server) and [Client](#client) refer to their docs +Only usable in Browser environment. For usage in [Server](#server) and [Client](#client) refer to their docs -### Declaration +## Declaration ```ts fw = { event: Browser, @@ -223,34 +278,128 @@ fw = { ``` Further documentation will describe the fields included in ``fw`` -### Cef +## Browser +Browser-side interactions -#### register -Registers CEF event +### register +Registers a browser event with an associated callback ```ts -fw.event.register('cefEventName', ([arg1, arg2]) => { - // your logic here +fw.event.register("showNotification", (message, color) => { + // do something }) ``` -#### trigger -Triggers registered CEF event with passed arguments. Formerly known as ``call`` or ``emit`` + +### unregister +Unregisters a browser event, removing the associated callback ```ts -fw.event.trigger('clientEventName', ['arg1', 2]) +fw.event.unregister("showNotification") ``` -#### triggerServer -Triggers registered client event with passed arguments. Formerly known as ``callServer`` or ``emitServer`` +### trigger +Triggers a browser event from the browser with arguments from shared types. Formerly known as ``call`` or ``emit`` ```ts -fw.event.triggerServer('serverEventName', ['arg1', 2]) +// without args +fw.event.trigger("browserEventName") +// with args +fw.event.trigger("browserEventName", ["message to me"]) ``` -#### triggerClient -Triggers registered client event with passed arguments. Formerly known as ``trigger`` +### triggerServer +Triggers a server event from the browser with arguments from shared types. Formerly known as ``callServer`` or ``emitServer`` ```ts -fw.event.triggerClient('clientEventName', ['arg1', 2]) +// without args +fw.event.triggerServer("serverEventName") +// with args +fw.event.triggerServer("serverEventName", ["message to server"]) ``` -## Features -### Event Middlewares -todo \ No newline at end of file +### triggerClient +Triggers a client event from the browser with arguments from shared types. Formerly known as ``callClient`` or ``emitClient`` +```ts +// without args +fw.event.triggerClient("clientEventName") +// with args +fw.event.triggerClient("clientEventName", ["message to client"]) +``` + +## Rpc +``rage-fw-rpc`` instance used under the hood. It is highly recommended to use this one if you need it instead of creating a new instance + +# Features +## Event Middlewares +Rage FW offers you to add middlewares when registering events in Client and Server environments, to check if callback should be executed or should not. Core class functionality is not exposed to user, but some types are for easier code managing. Here are some key points (in context of Server environment, but also applicable to Client) + +### Declaration +```ts +register( + eventName, + callback, + options?: { + middlewares?: RageFW_MiddlewareOptions + }, +) + +type RageFW_MiddlewareOptions = + | RageFW_MiddlewareFunction[] + | { + executables: RageFW_MiddlewareFunction[] + onError: (error: string) => unknown + } + +type RageFW_MiddlewareFunction = (...args: T.RageFW_ServerArgs) => + Promise + +type RageFW_MiddlewareResponse = + | { + success: boolean + message?: string + } + | boolean +``` + +### Usage +``RageFW_MiddlewareFunction`` can be imported to type your middlewares, eg.: +```ts +import {type RageFW_MiddlewareFunction} from '@entityseven/rage-fw-server' + +const isPlayerAdmin: RageFW_MiddlewareFunction<'yourEventName'> = async (player, ...args) => { + if (player.adminLvl >= 2) { + return true + } else { + return { + success: false, + message: 'You must have administrator rights for this action' + } + } +} + +// or function-like if you want to omit some argument types or hoisting is required + +async function isPlayerAdmin(player: PlayerMp, ...args): ReturnType> { + if (player.adminLvl >= 2) { + return true + } else { + return { + success: false, + message: 'You must have administrator rights for this action', + } + } +} + +fw.event.register( + 'yourEventName', + async (player, ...args) => { + // do an action which requires administrator rights + }, + { + middlewares: { + executables: [isPlayerAdmin], + onError: e => {}, // notify player about missing permissions + }, + }, +) +``` + +### Implementation TL;DR (why no next()?) +Unfortunately in Client-side of Rage:MP every thrown ``Error`` or ``Promise.reject`` is not ``catch``able, meaning a naughty error window will pop-up on player's screen. Due to this implementation variant we were forced to not throw ``Errors`` from middlewares and just return middleware result. Server-side can handle errors, but to keep everything consistent we stick up to this variant \ No newline at end of file