DOCSEARCHbyAlgolia
Submit Docs

WaveShield Documentation

website·Indexed 29 days ago

https://waveshielddocs-dev.justinnn.dev

Documentation for WaveShield anticheat, including installation guides, configuration for ACE permissions and whitelisting, developer exports for ban systems, and troubleshooting for common issues such as false bans, black screens, and event securing.

Tokens
3.4K
Snippets
19
Records
29
Agent score
50%

What's inside WaveShield

  2. Integrate WaveShield ban and kick events into custom scripts

    WaveShield provides internal server-side events that allow developers to trigger custom logic when players are banned, kicked, or unbanned. These events provide a data object containing detailed information about the action, including the ban ID, reason, player identifiers, and expiration timestamp.
    -- Triggered when a player is banned
AddEventHandler("__WaveShield_internal:playerBanned", function(source, data)
    -- Your custom logic here
end)

-- Triggered when a player is kicked
AddEventHandler("__WaveShield_internal:playerKicked", function(source, data)
    -- Your custom logic here
end)

-- Triggered when a player is unbanned
AddEventHandler("__WaveShield_internal:playerUnbanned", function(banId, data, unbanReason, from)
    -- Your custom logic here
end)

  3. Secure client events using WaveShield exports

    Client-side events can be secured by replacing the standard AddEventHandler with the WaveShield export version. This is recommended for events that could be exploited to give a player an unfair advantage.
    -- Replace this:
AddEventHandler("esx_ambulancejob:revive", function(...)
end)

-- With this:
exports["WaveShield"]:AddEventHandler("esx_ambulancejob:revive", function(...)
end)

  5. Install WaveShield anti-cheat for FiveM

    To ensure WaveShield functions correctly and all anti-cheat features are available, follow these critical installation requirements:

    1. Artifact Version: Use FiveM artifacts version 12882 or higher. Versions earlier than this may restrict certain anti-cheat features.
    2. Folder Placement: Place the WaveShield folder directly in the /resources directory. Do not place it inside a subfolder.
    3. Naming: Do not rename the script folder; it must be named exactly WaveShield.
    4. Load Order: In your server.cfg, ensure the WaveShield resource is started before any other resources.
    # Example server.cfg load order
ensure WaveShield
ensure other_resource_1
ensure other_resource_2

  6. Retrieve your WaveShield license key

    Upon purchasing a WaveShield product, the license key is sent automatically to the email address provided during the purchase process.

  7. Redeem WaveShield license key

    After purchasing WaveShield, you will receive an email containing a unique license key in an attached file. The license key follows the format waveshield-lifetime-xxxxxxxxxxxxx. To activate the product, navigate to the redeem page and enter this key into the provided panel. Once the key is successfully redeemed, you can proceed with the installation process.

  8. Secure server events using WaveShield exports

    To secure server-side events and prevent exploitation (such as unauthorized granting of money, weapons, or vehicles), replace standard FiveM event triggers and handlers with WaveShield exports. When securing an event, you must also remove the corresponding RegisterServerEvent or RegisterNetEvent function calls.

    Note: The documentation suggests that using the 'AI Anti Trigger Server Events' in the panel is the preferred modern method, but these manual exports remain functional.

    -- Client-side: Replace TriggerServerEvent
-- Replace: TriggerServerEvent("my_awesome_event", 999, "test")
exports["WaveShield"]:TriggerServerEvent("my_awesome_event", 999, "test")

-- Server-side: Replace AddEventHandler
-- Replace: AddEventHandler("my_awesome_event", function(number, string) ... end)
exports["WaveShield"]:AddEventHandler("my_awesome_event", function(source, number, string)
    print(number, string)
end)

  9. Configure WaveShield staff permissions via ACE

    WaveShield uses FiveM ACE permissions to grant staff access to in-game commands or to bypass the anticheat system. Permissions are assigned in the server.cfg file using any FiveM-supported identifier (license, Discord, Steam, etc.) or group. Note that adding a bypass is not always necessary, as the anticheat typically differentiates between staff actions and cheating behavior.
    # Grant access to WaveShield commands for a specific license
add_ace identifier.license:xxx "WaveShield.Commands" allow

# Grant anticheat bypass for a specific Steam ID
add_ace identifier.steam:xxx "WaveShield.Bypass" allow

# Grant anticheat bypass for an entire group (e.g., moderators)
add_ace group.mod "WaveShield.Bypass" allow

  10. Prevent false bans when using vMenu with WaveShield

    Because vMenu is developed in C#, WaveShield cannot automatically validate legitimate actions performed through the menu. To prevent false bans, you must manually disable the specific anti-cheat features in the WaveShield configuration that correspond to the vMenu features you are using. Additionally, ensure the vMenu resource is named exactly vMenu so that WaveShield can identify the resource and apply necessary internal adjustments.

  11. Resolve server crashes caused by obfuscated scripts when using WaveShield

    If your server crashes without a specific error message from WaveShield after installation, it is likely caused by an obfuscated script (often paid scripts) that detects WaveShield as a 'crack attempt' and prevents the server from starting. To resolve this, identify the problematic resource and add it to the ignored scripts list in the WaveShield configuration. Additionally, you must manually remove the WaveShield reference from that specific script's fxmanifest.lua file.
    -- Remove this line from the fxmanifest.lua of the crashing script
shared_script '@WaveShield/resource/waveshield.lua'

  12. Resolve false bans caused by WaveShield automatic event protection

    To fix false bans triggered by WaveShield's automatic event protection, ensure the following conditions are met:

    1. Remove Conflicting Resources: Disable or remove any other 'event protection' or 'anti-trigger' resources that interfere with the event system.
    2. Remove Function Overrides: Ensure no code overrides the TriggerServerEvent or TriggerLatentServerEvent functions. Overriding these functions can trigger false bans.
    3. Whitelist Non-Lua Scripts: Since WaveShield event protection currently only supports Lua scripts, you must whitelist events triggered by scripts written in C# or JavaScript.

    Warning: Do not add the problematic script to the 'ignored scripts' list; instead, resolve the issue using the methods above.

    -- Example of a forbidden override that causes false bans:
TriggerServerEvent = function(eventName, ...)
    local eventPayload = msgpack.pack({ ... })
    return a(0x7fdd1128, eventName, eventPayload, eventPayload:len())
end;