entityseven/rage-framework
2
2
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

updated descriptions

rilaxik 2024-10-30 15:27:00 +00:00
parent e1a0a6be2f
commit c4ef099b61
1 changed files with 236 additions and 87 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

323
Docs%400.2.0.md

@ -29,16 +29,16 @@ return true /*Promise<boolean>*/
}) })
``` ```
## Server # Server
Package used on a server-side of your Rage:MP Server Package used on a server-side of your Rage:MP Server
### Usage ## Usage
```ts ```ts
import { fw } from '@entityseven/rage-fw-server' import { fw } from '@entityseven/rage-fw-server'
``` ```
Only usable in server environment. For usage in [Client](#client) and [Browser](#browser) refer to their sections Only usable in server environment. For usage in [Client](#client) and [Browser](#browser) refer to their sections
### Declaration ## Declaration
```ts ```ts
fw = { fw = {
event: Server, event: Server,
@ -51,78 +51,105 @@ fw = {
``` ```
Further documentation will describe the fields included in ``fw`` Further documentation will describe the fields included in ``fw``
### Server ## Server
Handles event manipulations that do not require player to be present in context Server-side interactions
#### register ### register
Registers server event Registers a server event with an associated callback
```ts ```ts
fw.event.register('serverEventName', ([arg1, arg2]) => { fw.event.register("playerJoin", (player) => {
// your logic here // 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 ### unregister
Unregisters server event Unregisters a server event, removing the associated callback
```ts ```ts
fw.event.unregister('serverEventName') fw.event.unregister("playerJoin")
``` ```
#### trigger ### trigger
Triggers registered server event. Formerly known as ``call`` or ``emit`` Triggers registered server event. Formerly known as ``call`` or ``emit``
```ts ```ts
fw.event.trigger('serverEventName', ['arg1', 2]) fw.event.trigger('serverEventName', ['arg1', 2])
``` ```
### Player ## Player
Handles event manipulations that require player to be present in context Handles event manipulations that require player to be present in context
#### triggerClient ### triggerClient
Triggers registered client event with passed arguments. Formerly known as ``callClient`` or ``emitClient`` Triggers a client event from the server with arguments from shared types. Formerly known as ``callClient`` or ``emitClient``
```ts ```ts
fw.player.triggerClient('clientEventName', ['arg1', 2]) // without args
fw.player.triggerClient("clientEventName")
// with args
fw.player.triggerClient("clientEventName", ["message to client"])
``` ```
#### triggerBrowser ### triggerBrowser
Triggers registered CEF event with passed arguments. Formerly known as ``callBrowser`` or ``emitBrowser`` Triggers a browser event from the server with arguments from shared types. Formerly known as ``callBrowser`` or ``emitBrowser``
```ts ```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 Handles functions used to interact with system environment
#### Logger ### Logger
Used to log in a server console Used to log to a client in-game console
##### info #### info
Informational logs. Colored in white Informational logs. Colored in white
```ts ```ts
fw.system.log.info('some information to be logged') fw.system.log.info('some information to be logged')
``` ```
##### warn #### warn
Warning logs. Colored in yellow Warning logs. Colored in yellow
```ts ```ts
fw.system.log.info('warning message') fw.system.log.warn('warning message')
``` ```
##### error #### error
Error logs. Colored in red Error logs. Colored in red
```ts ```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 Package used on a client-side of your Rage:MP Server
### Usage ## Usage
```ts ```ts
import { fw } from '@entityseven/rage-fw-client' import { fw } from '@entityseven/rage-fw-client'
``` ```
Only usable in client environment. For usage in [Server](#server) and [Browser](#browser) refer to their docs Only usable in client environment. For usage in [Server](#server) and [Browser](#browser) refer to their docs
### Declaration ## Declaration
```ts ```ts
fw = { fw = {
event: Client, event: Client,
@ -135,86 +162,114 @@ fw = {
``` ```
Further documentation will describe the fields included in ``fw`` Further documentation will describe the fields included in ``fw``
### Client ## Client
Handles event manipulations that do not require player to be present in context Client-side interactions
#### register ### register
Registers client event Registers a client event with an associated callback
```ts ```ts
fw.event.register('clientEventName', ([arg1, arg2]) => { fw.event.register("playerDeath", (player, reason, killer) => {
// your logic here // 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 ### unregister
Unregisters client event Unregisters a client event, removing the associated callback
```ts ```ts
fw.event.unregister('clientEventName') fw.event.unregister("playerDeath")
``` ```
### Player ## Player
Handles event manipulations that require player to be present in context 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`` Triggers registered client event with passed arguments. Formerly known as ``call`` or ``emit``
```ts ```ts
fw.player.trigger('clientEventName', ['arg1', 2]) // without args
fw.player.trigger("clientEventName")
// with args
fw.player.trigger("clientEventName", ["message to me"])
``` ```
#### triggerServer ### triggerServer
Triggers registered client event with passed arguments. Formerly known as ``callServer`` or ``emitServer`` Triggers a server event from the client with arguments from shared types. Formerly known as ``callServer`` or ``emitServer``
```ts ```ts
fw.player.triggerServer('serverEventName', ['arg1', 2]) // without args
fw.player.triggerServer("serverEventName")
// with args
fw.player.triggerServer("serverEventName", ["message to server"])
``` ```
#### triggerBrowser ### triggerBrowser
Triggers registered CEF event with passed arguments. Formerly known as ``callBrowser`` or ``emitBrowser`` Triggers a browser event from the client with arguments from shared types. Formerly known as ``callBrowser`` or ``emitBrowser``
```ts ```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 ### Logger
Used to assign a browser instance. Returns the same browser instance Used to log to a client in-game console
```ts
fw.browser.registerBrowser(browserInstance)
```
### System #### info
Handles functions used to interact with system environment
#### Logger
Used to log in a client in-game console
##### info
Informational logs. Colored in white Informational logs. Colored in white
```ts ```ts
fw.system.log.info('some information to be logged') fw.system.log.info('some information to be logged')
``` ```
##### warn #### warn
Warning logs. Colored in yellow Warning logs. Colored in yellow
```ts ```ts
fw.system.log.info('warning message') fw.system.log.warn('warning message')
``` ```
##### error #### error
Error logs. Colored in red Error logs. Colored in red
```ts ```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 Package used on a browser-side of your Rage:MP Server
### Usage ## Usage
```ts ```ts
import { fw } from '@entityseven/rage-fw-browser' 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 ```ts
fw = { fw = {
event: Browser, event: Browser,
@ -223,34 +278,128 @@ fw = {
``` ```
Further documentation will describe the fields included in ``fw`` Further documentation will describe the fields included in ``fw``
### Cef ## Browser
Browser-side interactions
#### register ### register
Registers CEF event Registers a browser event with an associated callback
```ts ```ts
fw.event.register('cefEventName', ([arg1, arg2]) => { fw.event.register("showNotification", (message, color) => {
// your logic here // 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 ```ts
fw.event.trigger('clientEventName', ['arg1', 2]) fw.event.unregister("showNotification")
``` ```
#### triggerServer ### trigger
Triggers registered client event with passed arguments. Formerly known as ``callServer`` or ``emitServer`` Triggers a browser event from the browser with arguments from shared types. Formerly known as ``call`` or ``emit``
```ts ```ts
fw.event.triggerServer('serverEventName', ['arg1', 2]) // without args
fw.event.trigger("browserEventName")
// with args
fw.event.trigger("browserEventName", ["message to me"])
``` ```
#### triggerClient ### triggerServer
Triggers registered client event with passed arguments. Formerly known as ``trigger`` Triggers a server event from the browser with arguments from shared types. Formerly known as ``callServer`` or ``emitServer``
```ts ```ts
fw.event.triggerClient('clientEventName', ['arg1', 2]) // without args
fw.event.triggerServer("serverEventName")
// with args
fw.event.triggerServer("serverEventName", ["message to server"])
``` ```
## Features ### triggerClient
### Event Middlewares Triggers a client event from the browser with arguments from shared types. Formerly known as ``callClient`` or ``emitClient``
todo ```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<RageFW_MiddlewareResponse>
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<RageFW_MiddlewareFunction<'yourEventName'>> {
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