Script

Automatize user time tracking

The TimeCord script tracks time automatically from your game server, so players do not have to press a button in Discord. When a player comes on duty their linked Discord account is clocked in, and when they go off duty it is clocked out.

The current script is written in Lua for FiveM and supports the ESX framework.

Are you a good qbcore scripter and want to help us translate the script to qbcore? Get in touch on our Discord.

How it works

The script listens for the ESX esx:playerLoaded and esx:playerDropped events. When one fires, it reads the player's ESX job, looks up the API key you configured for that job, and sends an HTTP request to TimeCord, which handles the rest. TimeCord matches the player to their Discord account and clocks them in or out. In short: coming on duty clocks in, leaving clocks out.

Download

Get the script here: github.com/DanielLogisch/timecord_esx_script

Requirements

You need the Node.js runtime on the game server to install the script's dependencies.

• Windows: download the installer from nodejs.org and run it.

• Linux: follow this guide.

Installation

Windows

1. Go to your FXServer resources folder and unzip the script as a new folder.

2. Run windows_setup.bat to install the needed dependencies automatically.

3. Enable autostart by adding this to your server.cfg:

ensure timecord_esx_script-master

Linux

1. Go to your FXServer resources folder, create a new folder, and paste the script source there.

2. Go to the script path.

3. Make the setup script executable: chmod +x linux_setup.sh

4. Run it: ./linux_setup.sh

5. Update your server.cfg to enable autostart.

Importing the ESX object

Newer ESX versions import the shared object differently. If you are on a newer version, update the script accordingly:

// Old ESX object import
let ESX;
emitNet('esx:getSharedObject', (obj) => { ESX = obj })

// New ESX object import
const ESX = exports["es_extended"].getSharedObject();

Configuration

TimeCord ties an API key to each job. Map job names to keys in the script config:

// BASIC EXAMPLE
"api": {
    "police": "2c76b58e-fa2c-4a84-b9a9-fa79cd305864",
    "ambulance": "1c76258e-fa2c-4a84-b9a9-fa79cd305841"
}

The key is the exact job name as it appears in your database, so the script can check whether a player has that job. The value is the API key for the server your bot runs on. Generate keys in the dashboard under Settings -> Script. You can add as many jobs as you like, and only the jobs you list here are tracked.

In the dashboard's script settings, make sure the IP address of your game server is configured, otherwise requests are rejected. And never share your API key.

Custom duty event

If your server has an on/off-duty system where players toggle duty without leaving the server, use the custom event to clock them in or out. Pass true to clock in and false to clock out.

-- Note that this is a server / client event.
-- Protect the event so players cannot spam it, or you will get an API ban.

-- LUA CLIENT
TriggerServerEvent('timecord:dutyTrigger', playerId, true)  -- clock in
TriggerServerEvent('timecord:dutyTrigger', playerId, false) -- clock out

-- LUA SERVER
TriggerEvent('timecord:dutyTrigger', playerId, true)  -- clock in
TriggerEvent('timecord:dutyTrigger', playerId, false) -- clock out

-- JS CLIENT
emitNet('timecord:dutyTrigger', playerId, true)  -- clock in
emitNet('timecord:dutyTrigger', playerId, false) -- clock out

-- JS SERVER
emit('timecord:dutyTrigger', playerId, true)  -- clock in
emit('timecord:dutyTrigger', playerId, false) -- clock out

Troubleshooting

• esx:playerDropped not firing. Some servers report this event misbehaving, which can leave a session open. It may be overwritten by your ESX setup or another resource. Work around it by removing onNet('esx:playerDropped') from the script and replacing it with your own custom event, or by using the FiveM playerDropped event instead.

• A job is not being tracked. Confirm the job name in the config exactly matches the ESX job name, and that the API key for it is valid in your dashboard.

• Forgotten sessions. If a clock-out is ever missed, TimeCord's automatic clock-out closes sessions that stay open too long (see Statistics & Time).

Need help writing or extending a script? Open a ticket on our Discord.