FiniAC Resource API

INFO

This documentation covers the FiniAC Resource API, which allows you to integrate FiniAC with your custom server resources through events and commands.

Overview

The FiniAC Resource API provides server-side integration points that allow your resources to:

• Integrate with queue systems and connection handlers
• Trigger custom detections from your own anti-cheat logic

All API features run server-side and are designed to work seamlessly with FiniAC's detection and trigger systems.

Defer Events

FiniAC emits events during the player connection (deferral) process. These events allow you to integrate FiniAC with queue systems, custom connection handlers, or any logic that needs to run during the initial connection deferrals.

Why Use Defer Events?

Listening to FiniAC's defer events ensures that:

• Your queue system only displays after FiniAC has verified the player
• You avoid deferral message conflicts between FiniAC and your scripts
• You can make decisions based on whether FiniAC allowed or rejected the connection
• Your connection flow remains synchronized with FiniAC's security checks

Available Events

FiniAC:DeferStarted

Emitted when a player begins the connection verification process.

Parameters:

• source (string): The temporary player source ID during connection

When it fires:

• Immediately after the player begins connecting
• Before any security checks are performed
• Before the player receives a permanent source ID

FiniAC:DeferFinished

Emitted when FiniAC completes all connection verification checks.

Parameters:

• source (string): The player source ID
• joinAllowed (boolean): true if the player was allowed to join, false if they were rejected

When it fires:

• After all security checks (bans, VPN, trust score, etc.)
• After Terms of Service acceptance (if required)
• Just before the player fully joins or gets kicked

Usage Examples

Lua

-- Listen for when a player starts connecting
AddEventHandler("FiniAC:DeferStarted", function(source)
    print(("Player %s started FiniAC deferral"):format(source))
    -- Your queue logic can start here
end)

-- Listen for when FiniAC finishes verification
AddEventHandler("FiniAC:DeferFinished", function(source, joinAllowed)
    if joinAllowed then
        print(("Player %s passed FiniAC deferral"):format(source))
    else
        print(("Player %s was rejected by FiniAC"):format(source))
    end
end)

TypeScript

// Listen for when a player starts connecting
on("FiniAC:DeferStarted", (source: string) => {
  console.log(`Player ${source} started FiniAC deferral`);
  // Your queue logic can start here
});

// Listen for when FiniAC finishes verification
on("FiniAC:DeferFinished", (source: string, joinAllowed: boolean) => {
  if (joinAllowed) {
    console.log(`Player ${source} passed FiniAC deferral`);
  } else {
    console.log(`Player ${source} was rejected by FiniAC`);
  }
});

Best Practices

TIP

• Only display your server's Terms of Service, rule acceptance, etc. deferrals after FiniAC:DeferFinished has fired.
• Wait until FiniAC:DeferFinished before adding players to queue to avoid banned players taking up slots.

Custom Detection Command

The fini detect command allows you to trigger FiniAC detections from your own server resources. This is useful for integrating custom anti-cheat logic, detecting exploits in your scripts, or flagging suspicious behavior that your code detects.

Command Syntax

fini detect <source> <message>

Parameters:

• source (string|number): The player's source ID or license identifier
• message (string): Description of the detection. Use quotes if it contains spaces.

How It Works

1. Your resource detects suspicious behavior (e.g., plate swapping, inventory exploits)
2. You execute fini detect with the player source and a description
3. FiniAC creates a CommandDetection log entry
4. Your configured triggers can automatically ban, kick, or send webhooks based on the detection

Setting Up Permissions

Resources must have permission to execute the fini command. Add this to your server.cfg:

# Replace 'YourResourceName' with your actual resource name
add_ace resource.YourResourceName command.fini allow

Examples:

add_ace resource.ox_inventory command.fini allow
add_ace resource.qb-smallresources command.fini allow
add_ace resource.my_anticheat command.fini allow

Usage Examples

Basic Detection

Lua

-- Trigger a simple detection
local playerId = 5
ExecuteCommand(('fini detect %s "Suspicious behavior detected"'):format(playerId))

-- With spaces in the message (must use quotes)
ExecuteCommand(('fini detect %s "Player is plate swapping"'):format(playerId))

TypeScript

// Trigger a simple detection
const playerId: number = 5;
ExecuteCommand(`fini detect ${playerId} "Suspicious behavior detected"`);

// With spaces in the message (must use quotes)
ExecuteCommand(`fini detect ${playerId} "Player is plate swapping"`);

Detection from Client Event

This example shows how to trigger a detection when your server receives an event from a client, such as your custom anti-cheat detecting suspicious behavior:

Lua - Server

-- Server-side: Listen for suspicious activity from your client-side anticheat
RegisterServerEvent("myanticheat:suspiciousActivity")
AddEventHandler("myanticheat:suspiciousActivity", function(detectionType, detectionData)
    local src = source -- The player who triggered the event
    local playerName = GetPlayerName(src)

    -- Log the detection with FiniAC
    local message = ("%s - %s - %s"):format(playerName, detectionType, detectionData)
    ExecuteCommand(('fini detect %s "%s"'):format(src, message))
end)

TypeScript - Server

// Server-side: Listen for suspicious activity from your client-side anticheat
onNet(
  "myanticheat:suspiciousActivity",
  (detectionType: string, detectionData: string) => {
    const src = (global as any).source; // The player who triggered the event
    const playerName: string = GetPlayerName(src.toString());

    // Log the detection with FiniAC
    const message = `${playerName} - ${detectionType} - ${detectionData}`;
    ExecuteCommand(`fini detect ${src} "${message}"`);
  }
);

Client-side code example:

Lua - Client

-- Client-side: Detect suspicious activity and notify server
function DetectSuspiciousActivity(detectionType, detectionData)
    TriggerServerEvent("myanticheat:suspiciousActivity", detectionType, detectionData)
end

-- Example usage
if playerIsUsingInvalidWeapon then
    DetectSuspiciousActivity("InvalidWeapon", "Player has blacklisted weapon")
end

TypeScript - Client

// Client-side: Detect suspicious activity and notify server
function detectSuspiciousActivity(
  detectionType: string,
  detectionData: string
): void {
  emitNet("myanticheat:suspiciousActivity", detectionType, detectionData);
}

// Example usage
if (playerIsUsingInvalidWeapon) {
  detectSuspiciousActivity("InvalidWeapon", "Player has blacklisted weapon");
}

Custom detections appear in the FiniAC web panel under the Logs section with the type CommandDetection and the message containing your custom detection message.

Troubleshooting

Command Not Working

Problem: The fini detect command doesn't seem to trigger any detections.

Solutions:

1. Verify ACE permissions are set correctly in server.cfg:

   add_ace resource.YourResourceName command.fini allow

2. Check that FiniAC is running and initialized
3. Verify the source ID is valid and the player is connected
4. Check server console for any error messages

Message Formatting Issues

Problem: The detection message appears malformed or truncated.

Solutions:

1. Always wrap messages containing spaces in quotes
2. Escape special characters (quotes, backslashes) in your message
3. Keep messages under 1000 characters for best results
4. Avoid using newlines or special formatting in messages

Lua

-- ❌ Wrong - no quotes around message with spaces
ExecuteCommand('fini detect ' .. src .. ' This will not work')

-- ✅ Correct - quotes around message
ExecuteCommand(('fini detect %s "This will work"'):format(src))

-- ✅ Correct - escaping quotes in message
local message = 'Player said "hello"'
ExecuteCommand(('fini detect %s "%s"'):format(src, message:gsub('"', '\\"')))

TypeScript

// ❌ Wrong - no quotes around message with spaces
ExecuteCommand(`fini detect ${src} This will not work`);

// ✅ Correct - quotes around message
ExecuteCommand(`fini detect ${src} "This will work"`);

// ✅ Correct - escaping quotes in message
const message = 'Player said "hello"';
ExecuteCommand(`fini detect ${src} "${message.replace(/"/g, '\\"')}"`);