txAdmin Documentation

repository·master·Indexed 21 days ago

The official server management platform for FiveM and RedM. txAdmin provides a web panel and in-game menu for server deployment, player management, and monitoring. It is built into FXServer and includes tools for server.cfg validation, hardware diagnostics, process monitoring, and a recipe-based deployment system via the Deployer class.

Tokens: 31.1K
Snippets: 86
Records: 128
Agent score: 75%

What's inside txAdmin

Overview of txAdmin Broadcasted Events
master
txAdmin broadcasts server events to allow external resources to integrate with its functionality. All event names follow the pattern txAdmin:events:<name> and pass a single table containing relevant data as the first parameter.
Important Reliability Warning: Do not rely solely on these events for critical data consistency. Because events are broadcasted while the server is online, they may not trigger if an action (like whitelisting or banning) occurs while the server is offline. For critical logic, always verify state against your own database or the txAdmin data directly.
https://github.com/citizenfx/txadmin/blob/master/docs/events.md
Understand the Settings and Schema system
master
The txAdmin settings system relies on a schema to ensure data integrity and type safety.
Key Concepts
- config.json: Contains only the non-default values that have been changed.
- DEFAULT_NULL: Used for values that cannot have defaults (e.g., fxRunner.dataPath, discordBot.token).
- Schema Requirements: All schemas must define a default value, even if that value is null.
- schema.fixer: This utility runs during the boot process to fix invalid values. It is not used during saves. Its purpose is to ensure correct types, not to check dynamic requirements (like file existence).
- Fatal Errors: Use SYM_FIXER_FATAL for critical settings where txAdmin should refuse to boot rather than running with an invalid configuration.
- Validator Transformers: These are used to "polish" values (e.g., sorting or removing duplicates) rather than fixing invalid types.
https://github.com/citizenfx/txadmin/blob/master/docs/development.md
Handle txAdmin Healing Events in Frameworks
master
Because txAdmin is framework-agnostic, using the 'Heal' option in the menu may not automatically revive players in frameworks like ESX or QBCore (as they manage 'dead' states independently).
To ensure compatibility, developers should listen for the txAdmin:events:playerHealed event to trigger framework-specific revival logic.
https://github.com/citizenfx/txadmin/blob/master/docs/menu.md
Implement On/Off Duty Admin Validation
master
txAdmin provides a pattern for resources to manage or validate admin status (on/off duty) through exports:
1. Register a Validator: Register your resource as an 'on-duty validator'. When an authentication event occurs, txAdmin will reach out to your registered export to validate if the player should receive admin permissions.
2. Custom Error Messages: If validation fails, your export can return an error message in the format [resource] <custom message> to inform the user.
3. Manual Triggers: Use the provided export to manually trigger the admin authentication of a player or to trigger a setAdmin call to remove permissions.
https://github.com/citizenfx/txadmin/blob/master/docs/dev-notes.md
Understand the different txAdmin log types
master
txAdmin organizes logs into a directory structure at txData/<profile>/logs/. There are three primary log types:
1. Admin Logs: Records administrative actions (bans, warns, whitelists, settings changes, server restarts) and live console input. Note that player warn/ban/whitelist actions are also stored in the players database.
2. FXServer Console Log: Captures everything from the fxserver console (stdin, stdout, stderr). Live console inputs are prefixed with > .
3. Server Logs: Records in-game events such as player join/leave/die, chat messages, explosions, and commands. Player sources are formatted as [mutex#id] name. Searching for a specific [mutex#id] will reveal the player's identifiers starting from their join event.
https://github.com/citizenfx/txadmin/blob/master/docs/logs.md
Integrate txAdmin events with server resources
master
You can extend your server's functionality by listening to server events broadcasted by txAdmin. This allows your custom resources to react to txAdmin actions (like player bans, warnings, or scheduled restarts).
https://github.com/citizenfx/txadmin/blob/master/README.md
Follow Resource event naming rules
master
When creating or using events within the txAdmin resource, follow these naming conventions:
- Prefixes: Use tx<cl|sv>: to indicate the scope.
  txcl: for client-side events.
  txsv: for server-side events.
- Requests: Events that request information from the server (e.g., permissions) must start with txsv:req.
- Verbs: Use descriptive verbs, such as txsv:checkAdminStatus or txcl:setServerCtx.
- Scoping: Scoping events specifically to a menu is not required as most events are menu-related.
https://github.com/citizenfx/txadmin/blob/master/docs/development.md
Use Context Variables in Recipes
master
The deployer maintains a shared context between tasks. Variables are populated from the recipe's variables block and user input during the deployment process (Step 2).
Default Variables:
- deploymentID: Shortened recipe name + hex timestamp (e.g., PlumeESX_BBC957).
- serverName: Name specified during setup.
- recipeName, recipeAuthor, recipeVersion, recipeDescription: From recipe metadata.
- dbHost, dbPort, dbUsername, dbPassword, dbName, dbDelete, dbConnectionString: From database configuration input.
- svLicense: Required variable. The deployer automatically replaces {{svLicense}} in server.cfg at the end of deployment.
- serverEndpoints: The endpoint_add_xxxx (defaults to 0.0.0.0:30120 or uses TXHOST_INTERFACE & TXHOST_FXS_PORT).
- maxClients: Server slots (defaults to 48 or uses TXHOST_MAX_SLOTS).
Custom Variables: Define them in the variables block:
```
variables: 
    aaa: bbbb
    ccc: dddd
```
https://github.com/citizenfx/txadmin/blob/master/docs/recipe.md
Access the txAdmin In-Game Menu
master
The txAdmin in-game menu provides admin functionality and an online player browser directly within the game.
Access Methods
- Chat Commands: Use /tx or /txadmin in the chat.
- Keybind: You can map a keybind via Game Settings > Key Bindings > FiveM using the (txAdmin) Menu: Open Main Page option.
Permissions and Authentication
To access the menu, users must have a txAdmin account with either a Discord or Cfx.re identifier tied to it. Without these identifiers, access will be denied.
Specific menu options can be restricted by adjusting permissions within the txAdmin Admin Manager.
```
/tx
/txadmin
```
https://github.com/citizenfx/txadmin/blob/master/docs/menu.md
Use custom locales in txAdmin
master
If your preferred language is not available in the default list, or you wish to modify existing messages, you can provide a custom locale file.
1. Create a locale.json file.
2. Place the file inside the txData folder.
3. Use an existing language file from the txAdmin repository as a template.
4. Ensure the $meta.humanizer_language key is a value compatible with the humanize-duration library.
5. In the txAdmin settings, select the Custom language option.
Tip: To apply changes to a custom locale without restarting txAdmin or the server, edit the locale.json file and then click Save Global Settings in the settings page.
```
File location: txData/locale.json
```
https://github.com/citizenfx/txadmin/blob/master/docs/translation.md
Extend txAdmin UI with Adaptive Cards
master
Resources can add custom UI elements (buttons, inputs, etc.) directly into the txAdmin interface using an Adaptive Cards system. This does not require the new ACE system or the API.
To implement this, add a ui_cards definition to your resource's fxmanifest.lua. txAdmin will scan this and display the cards in the appropriate locations (NUI main tab, player card tab, or web panel).
Workflow:
1. Define cards in fxmanifest.lua.
2. When an admin interacts with a button in the UI, txAdmin sends an event via stdin to your resource.
3. Your resource verifies the caller and calls a specific exported function.
4. The exported function returns an adaptive card object, which txAdmin renders via fd3.
```
ui_cards 'list' {
    ['playerInfo'] = {
        title = 'RP Info',
        type = 'player', -- shows in player card
    },
    ['generalStatsNui'] = {
        title = 'RP Stats',
        type = 'mainmenu', -- shows in nui main menu
    },
    ['generalStatsWeb'] = {
        title = 'RP Stats',
        type = 'web', -- shows in the web panel
    },
}
```
https://github.com/citizenfx/txadmin/blob/master/docs/dev-notes.md
Create a Recipe for Server Deployment
master
A Recipe is a YAML document used by txAdmin's Server Deployer to automate server setup, including downloading resources and configuring server.cfg. Recipes are 'jailed' to the target folder for security. At the end of deployment, txAdmin verifies the presence of a server.cfg and a resources folder.
To create a recipe, define metadata (name, version, author, description), custom variables, and a sequence of tasks.
```
name: PlumeESX2
version: v1.2.3
author: Toybarra
description: A full featured ESX v2 base.

variables:
    dbHost: localhost
    dbUsername: root
    dbPassword: ""
    dbName: null

tasks: 
    - action: download_file
      url: https://github.com/citizenfx/cfx-server-data/archive/master.zip
      path: ./tmp/cfx-server-data.zip

    - action: another_task
      optionA: aaaa
      optionB: bbbbbb
```
https://github.com/citizenfx/txadmin/blob/master/docs/recipe.md

txAdmin Documentation

What's inside txAdmin

Key Concepts

Access Methods

Permissions and Authentication