Custom scripts - Documentation

Introduction

In this tutorial, we'll walk you through the process of creating your own custom scripts for FiveM. First will be guiding you through setting up the resource and explaining some basics and after that we'll be importing some modules of the Mercy Framework. If you have any problems following this tutorial, please join our discord server, we will be happy to help you there!

Useful links

Let's get started

Creating the project

Open your server resources folder with any text editor.
Create a new folder for your script (e.g., my_custom_script).

Creating the fxmanifest.lua file

Create a file named fxmanifest.lua in your my_custom_script folder and add the following content:

fx_version 'cerulean'
game 'gta5'

author 'Mercy Collective'
description 'My custom resource!'
version '1.0.0'

client_script 'client/cl_*.lua'
server_script 'server/sv_*.lua'

This manifest file specifies the basic information about your script, such as its name, author, and associated script files.

Client and server-side files.

Let's create a file called "cl_main.lua" in the client folder and open it.

You can paste the piece of code below into this, this code will create you a new command called "/mycustomcommand".

We created a new variable called "mercy" and assigned a string to it (a string is text). Then we print the variable with a piece of text in front of it and behind it.

RegisterCommand('mycustomcommand', function()
    local mercy = "Mercy Collective"
    print('We are ' ..mercy.. '!')
end, false)

Once you run this command you will get the following output:

script:my_custom_script | We are Mercy Collective!

Let's create a server-side command that prints the player's name to the server console when it runs the command. Create a file called sv_main.lua in the server folder and open it.

Paste this code into the server-side file and restart your script using ensure <resource name>.

RegisterCommand('myservercommand', function(source, args, rawCommand)
    local playerName = GetPlayerName(source)
    print('Player ' .. playerName .. ' executed the command:' ..rawCommand)
end, true)

If you run this command you will get something like this in your server console:

  [script:my_custom_script] Player Razer excuted the command: myservercommand

Importing modules

The framework uses modules to import functions to use across all scripts. This helps with performance and only imports the right amount of functions into the scripts.

Client side

In the client side or cl_main.lua you'll need to do following steps:

Define the modules you would like to use at the top, for example:

Modules = {}
RequestedModules = {
    'Player',
    'Events',
    'Callback'
    'Functions'
}

As you can see you should put the modules you would like to use inside the RequestedModules variable. For the available modules please look on the Modules page.

Import the modules by placing the following code under the defined modules, the code should now look like this:

Modules = {}
local RequestedModules = {
    'Player',
    'Events',
    'Callback'
    'Functions'
}

local _Ready = false
AddEventHandler('Modules/client/ready', function()
    TriggerEvent('Modules/client/request-dependencies', RequestedModules, function(Succeeded)
        if not Succeeded then return end
        for i = 1, #RequestedModules, 1 do
            local ModuleName = RequestedModules[i]
            Modules[ModuleName] = exports['mercy-base']:FetchModule(ModuleName)
        end
        _Ready = true
    end)
end)

The code above will request the dependencies given within the array, to make sure they are working fine. If so, it will fetch and add the module data to the Modules variable. You would use the Modules now by using the following prefix: Modules.MODU_NAME.FUNC_NAME (eg. Modules.Events.TriggerServer) Add a "local" prefix infront of the variable if you don't need to use the Modules in a different file. If you do, just remove "local".

Let's start using the modules, we'll be printing the stateid of the player when the /stateid command is used:

RegisterCommand('stateid', function()
    local Player = Modules.Player.GetPlayerData()
    local StateId = Player.CitizenId
    print('My stateid is ' ..StateId.. '!')
end, false)

For the second example we'll be triggering a protected event that we'll be making in the server side in a moment:

Modules.Events.TriggerServer('mercy-customscript/example-event', 'This is a test')

Make sure to put this code within a command, event or function, else you'll have to wait until the values of the modules are fetched.

The requested modules will now be imported in the client side of the script and are available for use!

Server side

In the server side or sv_main.lua you'll need to do following steps:

Define the modules you would like to use at the top, for example:

Modules = {}
local RequestedModules = {
    'Player',
    'Events',
    'Callback'
    'Functions'
}

As you can see you should put the modules you would like to use inside the RequestedModules variable For the available modules please look on the Modules page.

Import the modules by placing the following code under the defined modules, the code should now look like this:

Modules = {}
local RequestedModules = {
    'Player',
    'Events',
    'Callback'
    'Functions'
}

local _Ready = false
AddEventHandler('Modules/server/ready', function()
    TriggerEvent('Modules/server/request-dependencies', RequestedModules, function(Succeeded)
        if not Succeeded then return end
        for i = 1, #RequestedModules, 1 do
            local ModuleName = RequestedModules[i]
            Modules[ModuleName] = exports['mercy-base']:FetchModule(ModuleName)
        end
        _Ready = true
    end)
end)

The code above will request the dependencies given within the array, to make sure they are working fine. If so, it will fetch and add the module data to the Modules variable. You would use the Modules now by using the following prefix: Modules.MODULE_NAME.FUNCTION_NAME (eg. Modules.Events.RegisterServer) *Add a "local" prefix infront of the variable if you don't need to use the Modules in a different file. If you do, just remove "local".

To use modules in the server side you'll have to make sure the requested module values are set on the variables. This will be checked by the following code:

CreateThread(function()
    while not _Ready do
        Wait(100)
    end

    -- Start using modules here

    Modules.Events.RegisterServer('mercy-customscript/server/example-protected-event', function(Source, Variable1, Variable2)
        print('This is a test!')
    end)
end)

The above code will wait until the values are set so they are ready to be used. Make sure to put your code within the CreateThread otherwise it won't work.

Let's start using the modules, let's create a protected event:

Modules.Events.RegisterServer("mercy-customscript/example-protected-event", function(Source, Text)
    local Player = Modules.Player.GetPlayerBySource(Source)
    if not Player then return end -- Check to make sure player exists.

    print(Text..' by '..Player.PlayerData.Name..'!')
end)

Don't forget to put code that is using the modules within the CreateThread.

When you've done above steps and trigger the protected event like we did a moment ago, you'll get following output:

This is a test by YOUR_NAME!

The requested modules will now be imported in the server side of the script and are available for use!

Ready

Now that both sides have their modules imported you can start using them to create your custom scripts.