[Discussion]: Export driven developer API in monitor script

[TasoOneAsia]

Scope

Developer API

Feature Description

Summary Provide a public API for third party resources to trigger methods or fetch useful data within txAdmin.

API Scope This export API should be limited mainly to txAdmin Game Script related functionality defined in the scripts folder. No relaying of data should be done through game scripts as a means of communicating with the txAdmin backend.

Possible Concerns

• What limitations should we establish for exposing internal methods & data?
• Should we tie txAdmin player state directly into a state bag, or should we prevent undefined behavior by not allowing for this data to be directly mutated by a user?

This API's structure and scope is not final and is open to feedback and comments from contributors and users.

Use Case

• Enables implementation of #390 through export calls
• Tie into menu state for correct handling of players (Ex. To check if a player has been frozen by a server moderator before modifying a ped's state)

We encourage you share any use cases for exports that you may find useful

Additional Info

Proposed Examples:

--- An export returning whether a player has a given txAdmin permission
--- if the player has the 'all_permissions' flag, this function will always
--- return true.
--- @param playerSrc number|string The target player's server ID
--- @param permission string The permission to check against
local function doesPlayerHavePermission(playerSrc, permission)
  return PlayerHasTxPermission(playerSrc, permission)
end
exports('doesPlayerHavePermission', doesPlayerHavePermission)

--- Add an announcement using the in-game menu announcement
--- alerts.
--- @param msg string The announcement message to display
local function addAnnouncement(msg)
  TriggerClientEvent('txAdmin:receiveAnnounce', -1, msg)
end
exports('addAnnouncement', addAnnouncement)

See the following somewhat related issues #179, #436

[TasoOneAsia]

As stated in the PR's description, none of the implementation details above are considered final and are open to suggestions

[MonsterZockerHD]

Sup, so basically what I would need and probably many others too are functions for:

• banning a player
• kicking a player
• warn a player
• send stuff to server log easily, not something like (TriggerServerEvent('txaLogger:DebugMessage', 'Goats are ugly')

Banning a player Would be nice to have for Anticheats to trigger. Therefore, a function would need to contain: script-label (to identify the resource it's coming from more easily), player, reason

Kicking a player Would be nice to have for Anticheats to trigger too (And similar detection methods, like the ones included in some ESX-based scripts). Therefore, a function would need to contain: script-label (to identify the resource it's coming from more easily), player, reason

Warn a player Would be nice to have for Anticheats to trigger, in addition it could be useful for people using bad words in the chat or other similar stuff. : Therefore, a function would need to contain: script-label (to identify the resource it's coming from more easily), player, reason

and the most important function: Sending stuff to the log more easily. A function would need to contain the options: script-label (to identify the resource it's coming from more easily), player, message, category

Feel free to reply.

[Druganov1]

Yes, this would be so nice, since right now we have 3 possible ways that player can get banned

1. TxAdmin
2. Anticheat
3. Fake triggers, we use el_bwh currently to ban people that execute fake triggers

It would make it so easier to just have a server event like

RegisterServerEvent('txadmin:events:banplayer') AddEventHandler('txadmin:events:banplayer', function(playerid, reason, expire) end)

expire, if you enter never the ban will be permanent, but you also can have syntaxes like 1d 1h 1j 1w 1m and so on

[DamonOnYT]

Playtime (Both Server & Client Hooks)

I'd love to see something that would allow me to easily get the playtime of a player, both in seconds (if its recorded in such way) and also the displayed date.

An example for a use case would be the following

AddEventHandler('playerConnecting', function(name, setKickReason, deferrals)

// defferal stuff here

	local license = ExtractIdentifiers(src).license;
        local playtime = exports.txAdmin:GetPlaytime(license, "seconds")
 
 // I would use it to give an ace perm here,

// end defferal
end)

[Alexr03]

**Playtime *(Both Server & Client Hooks ***

I'd love to see something that would allow me to easily get the playtime of a player, both in seconds (if its recorded in such way) and also the displayed date.

An example for a usecase would be the following

AddEventHandler('playerConnecting', function(name, setKickReason, deferrals)

// defferal stuff here

	local license = ExtractIdentifiers(src).license;
        local playtime = exports.txAdmin:GetPlaytime(license, "seconds")
 
 // I would use it to give an ace perm here,

// end defferal
end)

+1 this. Would be great to get this data

[ItsVinnyX]

**Playtime *(Both Server & Client Hooks *** I'd love to see something that would allow me to easily get the playtime of a player, both in seconds (if its recorded in such way) and also the displayed date. An example for a usecase would be the following

AddEventHandler('playerConnecting', function(name, setKickReason, deferrals)

// defferal stuff here

	local license = ExtractIdentifiers(src).license;
        local playtime = exports.txAdmin:GetPlaytime(license, "seconds")
 
 // I would use it to give an ace perm here,

// end defferal
end)

+1 this. Would be great to get this data

Uhm... yes PLEASE!

[XenoSphinx]

Sup, so basically what I would need and probably many others too are functions for:

* banning a player

* kicking a player

* warn a player

* send stuff to server log easily, not something like `(TriggerServerEvent('txaLogger:DebugMessage', 'Goats are ugly')`

Banning a player Would be nice to have for Anticheats to trigger. Therefore, a function would need to contain: script-label (to identify the resource it's coming from more easily), player, reason

Kicking a player Would be nice to have for Anticheats to trigger too (And similar detection methods, like the ones included in some ESX-based scripts). Therefore, a function would need to contain: script-label (to identify the resource it's coming from more easily), player, reason

Warn a player Would be nice to have for Anticheats to trigger, in addition it could be useful for people using bad words in the chat or other similar stuff. : Therefore, a function would need to contain: script-label (to identify the resource it's coming from more easily), player, reason

and the most important function: Sending stuff to the log more easily. A function would need to contain the options: script-label (to identify the resource it's coming from more easily), player, message, category

Feel free to reply.

Along with this I also suggest an API integration where the bot can come back with the status and connection info for the server (as of now I can add in the simple line of code to reply with the connection information. but would like to have it added where the API also returns with online/offline using a simple check of the server IP (I might be overthinking and thinking it maybe just something i can code into the bot to ping the IP address and have it return with online/offline.))

[NextZac]

This could come in useful for a lot of things. Currently working on creating a website where administrators can have access to not only FiveM Features, but also for other administrative things. This would let me create a resource where I could push data via Pusher to my Laravel PHP server and get info about Players and the Server itself. Allowing me to log and use the information to my liking. Having it stored in one place is quite a big thing for me, as it allows administrators to work quicker and not having multiple accounts for different things.

I get that I could already do this, but this API would make it so much easier for everyone. Would be a great addition in my honest opinion.

Having the ability to use txAdmin accounts for checking permission in game would make it also way easier to identify when and who used a command/event. And thus being able to log it into one place.

[Alexr03]

This could come in useful for a lot of things. Currently working on creating a website where administrators can have access to not only FiveM Features, but also for other administrative things. This would let me create a resource where I could push data via Pusher to my Laravel PHP server and get info about Players and the Server itself. Allowing me to log and use the information to my liking. Having it stored in one place is quite a big thing for me, as it allows administrators to work quicker and not having multiple accounts for different things.

I get that I could already do this, but this API would make it so much easier for everyone. Would be a great addition in my honest opinion.

Having the ability to use txAdmin accounts for checking permission in game would make it also way easier to identify when and who used a command/event. And thus being able to log it into one place.

I'm in a similar boat. We also have a custom admin panel for our staff and our players to trade vehicles with eachother, do administrative tasks or for staff to screenshot players screens/kick/ban etc.

The main data I am looking to get from txAdmin is the Play time/session time and a REST API or exports to kick/ban players. Something that allows me to sort my own player list of the most recently joined players. Turns out this is really helpful for catching hackers.

[Rhydium]

Sup, so basically what I would need and probably many others too are functions for:

• banning a player
• kicking a player
• warn a player
• send stuff to server log easily, not something like (TriggerServerEvent('txaLogger:DebugMessage', 'Goats are ugly')

Banning a player Would be nice to have for Anticheats to trigger. Therefore, a function would need to contain: script-label (to identify the resource it's coming from more easily), player, reason

Kicking a player Would be nice to have for Anticheats to trigger too (And similar detection methods, like the ones included in some ESX-based scripts). Therefore, a function would need to contain: script-label (to identify the resource it's coming from more easily), player, reason

Warn a player Would be nice to have for Anticheats to trigger, in addition it could be useful for people using bad words in the chat or other similar stuff. : Therefore, a function would need to contain: script-label (to identify the resource it's coming from more easily), player, reason

and the most important function: Sending stuff to the log more easily. A function would need to contain the options: script-label (to identify the resource it's coming from more easily), player, message, category

Feel free to reply.

In addition to this I (and probably many others) would also like to be able to request a player history (with their previous warns, bans, kicks, etc.). So basically all the administrative tasks should be included.

[roobr]

Would be good to add in:

• an export for turning on and off the player whitelist from serverside export (ultimately use it in our own discord bot)
• an export to add notes to a player (ultimately use it in our own discord bot for out of game moderation)

For example: we have a PVP server that is only up during a set timeframe and would like to automate the server to unwhitelist when the time frame has been reached, and also be able to write a bot to be able to allow people on discord to vote for the server to come up earlier (irrelevant to this)

I also agree with the playertime export, can be used really well to catch hackers (money vs playtime) and show up on the loading screen (we currently use the players.json and read it each time a player joins to do this without tx having any export in)

Thanks for your time

[menstruated]

Anything such as triggering a server event to restart such as txAdmin:RestartServer, allowing me to use a permission framework that would mean players with certain groups could trigger server restarts. Rather than relying on giving them perms via the cfg using identifiers. Would also make it dynamic, meaning I wouldn't have to restart the serve to allow people perms, nor give them access to the txAdmin menu entirely.

[Dalrae1]

All of these ideas would be awesome to add. Banning, kicking, warning, restarting, stopping, or starting resources, getting player info such as playtime and join date, as well as all player punishment history. Settings such as the Restarter feature would be a nice add, however not something that I would consider to be very useful if a simple restart export is added. A way to get server diagnostic data would be extremely useful too.

[tabarra]

Just a quick note here on the thread: We are not actively replying but we are 100% taking note of everything being requested.
Keep the feedback coming, they are great.

[TasoOneAsia]

A way to get server diagnostic data would be extremely useful too.

What data specifically are you looking to consume? @Dalrae1

[Dalrae1]

What data specifically are you looking to consume?

I was thinking everything in the "diagnostics" tab, so:

• Server uptime
• Enviroment details (Node version, operating system, CPU & memory usage)
• txAdmin version

General stuff like that @TasoOneAsia

[TasoOneAsia]

What data specifically are you looking to consume?

I was thinking everything in the "diagnostics" tab, so:

• Server uptime

• Enviroment details (Node version, operating system, CPU & memory usage)

• txAdmin version

General stuff like that

A lot of this data is already available through default APIs, in the same manner txAdmin retrieves this info. I'm concerned that such an abstraction would serve no purpose if it isn't only attainable through a txAdmin API.

[Dalrae1]

What data specifically are you looking to consume?

I was thinking everything in the "diagnostics" tab, so:

• Server uptime
• Enviroment details (Node version, operating system, CPU & memory usage)
• txAdmin version

General stuff like that

A lot of this data is already available through default APIs, in the same manner txAdmin retrieves this info. I'm concerned that such an abstraction would serve no purpose if it isn't only attainable through a txAdmin API.

I don't know what data you're referring to, other than "Server Uptime" (Which would require a separate resource to reliably get) With environment details, it is possible to retrieve this info with c# or Javascript, though if using lua, a c# or Javascript wrapper would be required to retrieve any of that information. Afaik, the txAdmin version is not externally accessible via any means.

Though much of the information is possible to get, having a separate resource (Such as txAdmin), which already uses this information, to act as an API to retrieve it would be very convenient. Similar to the "baseevents" resource included in cfx-server-data

@TasoOneAsia

[TasoOneAsia]

@Dalrae1 Thanks; we'll keep this suggestion in mind. My hesitation for adding an abstraction of this sort is just that it further increases the API surface that we need to maintain actively.

As you said, you can retrieve env information using a C# or JS resource implementation for the timebeing. If you'd like to retrieve the txAdmin version, you can use the following non-replicated ConVar txAdmin-version; keep in mind that this isn't formally documented and (although unlikely) may be subject to change in future versions.

Edit: At the end of the day, we would like to scope this API strictly to txAdmin functionality, and you can see how sys information abstraction of this sort does not fall under the scope of strictly tx functionality.

[Dalrae1]

@Dalrae1 Thanks; we'll keep this suggestion in mind. My hesitation for adding an abstraction of this sort is just that it further increases the API surface that we need to maintain actively.

As you said, you can retrieve env information using a C# or JS resource implementation for the timebeing. If you'd like to retrieve the txAdmin version, you can use the following non-replicated ConVar txAdmin-version; keep in mind that this isn't formally documented and (although unlikely) may be subject to change in future versions.

Edit: At the end of the day, we would like to scope this API strictly to txAdmin functionality, and you can see how sys information abstraction of this sort does not fall under the scope of strictly tx functionality.

Alright, that makes sense

[TasoOneAsia]

Add the ability to dynamically add menu items defined by third party resources, to the "Main" page. A possible implementation could resemble the following:

exports.monitor:addDialogOption({
  id = 'myDialogOption',
  onSubmit = function(submittedString)
    print('submitted string')
  end
})

exports.monitor:addAction({
  id = 'myOtherAction'
  onSubmit = function()
    print('do sopmething')
  end
})

[tabarra]

Note to self: when drawing the ban api, break it into two, one to ban players and one called "legacy ban" that you can pass the identifiers, since this is compatible with current and also the future database changes.

[locomoco28]

I'm surprised that no one has mentioned the use of accessing logs just yet!
I've seen that the console view uses a websocket for live logs which is what I'm interested in getting to be able to display logs in a custom admin panel which would allow for further processing of logs and adding more filtering options specific to the server.

Another usecase for accessing logs would be the implementation of a centralized logging aggregation tool like Grafana Loki.

The websocket server is checking for auth of the user using the session from the cookie which is the logged in user's session.

What automated systems would need is an API key that can be created by administrators. This key should be able to authorize for REST APIs and Websockets.
API Key creation should have its own permission in txAdmin so only selective administrators can create and regenerate them.

[TasoOneAsia]

@locomoco28 Although I 100% agree that some sort of logging bridge for transport to log aggregation and management systems is a very valid use case, keep in mind that this initial public API is scoped only to in-game exports and will not include anything else, such as HTTP endpoints.

[tabarra]

An export to change tx whitelist mode, more details on #740.

[Miicker]

The possibility to retrieve playtime, for example:

-- load txadmin api
local txadmin_api = exports["txadmin_api"]

-- command to get playtime
RegisterCommand("playtime", function(source, args)
  local player = GetPlayerIdentifiers(source)[1] -- get player id
  txadmin_api.getPlayer(player, function(playerData)
    if playerData then
      local totalTime = playerData.playTimeTotal -- get playtime
      TriggerClientEvent("chatMessage", source, "SERVER", {255, 255, 255}, "Your total playtime is: " .. totalTime .. " minutes")
    else
      TriggerClientEvent("chatMessage", source, "SERVER", {255, 0, 0}, "There was an error retrieving the data")
    end
  end)
end)

[GrandpaRex]

I'd like to be able to pull the last connection date, would like to use this to track activity. This in combination with playtime would be awesome features!

[adweex]

Yep. Would be great to harvest some data from tx. Like playtime

[ghost]

Ability to ban others with other resources using txadmin, for example if they trigger something then it will ban them with txadmin with an event.

[roobr]

I can assist you guys with the resource I have made that parses the player data json to get connection time and playtime ect.

Although the functionality implemented would be great to be able to ban ect

Get Outlook for iOShttps://aka.ms/o0ukef

---

From: jenniferr0 @.> Sent: Tuesday, April 11, 2023 10:06:21 AM To: tabarra/txAdmin @.> Cc: roobr @.>; Comment @.> Subject: Re: [tabarra/txAdmin] [Discussion]: Export driven developer API in monitor script (#442)

Ability to ban others with other resources using txadmin, for example if they trigger something then it will ban them with txadmin with an event.

— Reply to this email directly, view it on GitHubhttps://github.com/tabarra/txAdmin/issues/442#issuecomment-1502492966, or unsubscribehttps://github.com/notifications/unsubscribe-auth/ACFFR7OY5NTHZ5V7Y45YRLLXASN73ANCNFSM5DXZ4LEA. You are receiving this because you commented.Message ID: @.***>