MarkerManager Docs / Example

--[[
    -------------------- MarkerManager Documentation and Example by Kiminaze --------------------

    Here you can find a complete documentation of what is possible with the MarkerManager.

    At the bottom you can find an example on how you could use it.

    Installation Instructions:
        Put this folder somewhere in your resources-folder and put "start MarkerManager" into your
        server.cfg. It should be ABOVE all scripts that use the MarkerManager. Other than that,
        there are no dependencies and you can put it anywhere.
        If you want to also see the example below ingame, you need to uncomment the line from the
        fxmanifest.lua.

        If you want debug messages in the console: Go into the config.ini and set debugMode from
        false to true.

    Critical Information:
        Make sure to use names that can easily be distinguished for your markers! No marker should
        have the same name! The newest one with the same name WILL override the last one. There is
        also a debug message in the console if that should happen.
        You could call them "ScriptName:FunctionName" (e.g. "GarageScript:SpawnVehicle",
        "PoliceJob:OpenBossMenu" or "Racing:StartRace")

        If you want to also delete the markers when the script is stopped, you need to delete them
        manually. The easiest way is to delete them in the EventHandler for "onResourceStop".
        (see at the end of this script for an example)

        If you registered a marker with a function, make sure you also have an event with the SAME
        name!



    List of all available events with their parameters (you can directly copy these into your
    Lua-scripts and replace the variables):

    -- registers a new marker
        TriggerEvent("MarkerManager:Register",
            name,               -- string:  name of the marker (must be individual!)
            viewDistance,       -- float:   view distance of the marker (in units / meters)
            markerType,         -- int:     type id of the marker
            position,           -- vector3: position of the marker
            scale,              -- vector3: scale of the marker
            color               -- vector4: color of the marker (Format: RGBA)
        )

    -- registers a new marker but without the visual component (make sure to also register a function after this)
        TriggerEvent("MarkerManager:RegisterNoMarker",
            name,               -- string:  name of the interaction point (must be individual!)
            position,           -- vector3: position of the interaction point
            radius              -- float:   the radius of the interaction point
        )

    -- register a new, advanced marker
        TriggerEvent("MarkerManager:RegisterAdvanced",
            name,               -- string:  name of the marker (must be individual!)
            viewDistance,       -- float:   view distance of the marker (in meters)
            markerType,         -- int:     type id of the marker
            position,           -- vector3: position of the marker
            rotation,           -- vector3: rotation of the marker
            scale,              -- vector3: scale of the marker
            color,              -- vector4: color of the marker (Format: RGBA)
            bobUpAndDown,       -- bool:    should the marker bob up and down? (true / false)
            faceCamera,         -- bool:    should the marker face the camera? (true / false)
            rotating            -- bool:    should the marker be rotating? (true / false)
        )

    -- deletes a marker
        TriggerEvent("MarkerManager:Delete",
            name                -- string:  name of the marker that should be deleted
        )

    -- adds a function to an existing marker with a button press
        TriggerEvent("MarkerManager:AddFunction",
            name,               -- string:  name of the marker that should trigger this event
            eventName,          -- string:  the name of the event that should be triggered when the button is pressed
            helpText,           -- string:  the help text in the top left corner of the screen
            button              -- int:     the button to press to execute the function
        )

    -- adds a function to an existing marker that gets automatically triggered, when a player enters the marker
        TriggerEvent("MarkerManager:AddEnterFunction",
            name,               -- string:  name of the marker that should trigger this event
            eventName           -- string:  the name of the event that should be triggered when the player enters
        )

    -- adds a function to an existing marker that gets automatically triggered, when a player exits the marker
        TriggerEvent("MarkerManager:AddExitFunction",
            name,               -- string:  name of the marker that should trigger this event
            eventName           -- string:  the name of the event that should be triggered when the player exits
        )

    -- attaches an existing marker to an entity
        TriggerEvent("MarkerManager:AttachToEntity",
            name,               -- string:  the name of the marker that should be attached to an entity
            entityId,           -- int:     the id of the entity
            offset              -- vector3: the offset in relations to the entity as a vector3
        )

    -- detaches an existing marker from any entity it is attached to
        TriggerEvent("MarkerManager:Detach",
            name                -- string:  the name of the marker that should be detached from an entity
        )

    -- enables or disables a marker from showing (and its function)
        TriggerEvent("MarkerManager:Enable",
            name                -- string:  the name of the marker that should be enabled / disabled
            enable              -- bool:    should the marker be enabled or disabled (true or false)
        )

    -- changes the view distance of the marker
        TriggerEvent("MarkerManager:ChangeViewDistance",
            name                -- string:  the name of the marker that should have its value changed
            viewDistance        -- float:   the new view distance
        )

    -- changes the type of the marker
        TriggerEvent("MarkerManager:ChangeType",
            name                -- string:  the name of the marker that should have its value changed
            type                -- int:     the new marker type
        )

    -- changes the position of the marker
        TriggerEvent("MarkerManager:ChangePosition",
            name                -- string:  the name of the marker that should have its value changed
            position            -- vector3: the new position
        )

    -- changes the rotation of the marker
        TriggerEvent("MarkerManager:ChangeRotation",
            name                -- string:  the name of the marker that should have its value changed
            rotation            -- vector3: the new rotation
        )

    -- changes the scale of the marker
        TriggerEvent("MarkerManager:ChangeScale",
            name                -- string:  the name of the marker that should have its value changed
            scale               -- vector3: the new scale
        )

    -- changes the color of the marker
        TriggerEvent("MarkerManager:ChangeColor",
            name                -- string:  the name of the marker that should have its value changed
            color               -- vector4: the new color
        )

    -- changes if the marker should bob up and down
        TriggerEvent("MarkerManager:ChangeBobUpAndDown",
            name                -- string:  the name of the marker that should have its value changed
            bobUpAndDown        -- bool:    the new bob up and down behaviour
        )

    -- changes if the marker should face the camera
        TriggerEvent("MarkerManager:ChangeFaceCamera",
            name                -- string:  the name of the marker that should have its value changed
            faceCamera          -- bool:    the new face camera behaviour
        )

    -- changes if the marker should be rotating
        TriggerEvent("MarkerManager:ChangeRotating",
            name                -- string:  the name of the marker that should have its value changed
            rotating            -- bool:    the new rotating behaviour
        )


    additional information can be found here:
     - markers: https://docs.fivem.net/docs/game-references/markers/
     - vector3: https://docs.fivem.net/docs/scripting-reference/runtimes/lua/functions/vector3/
     - vector4: https://docs.fivem.net/docs/scripting-reference/runtimes/lua/functions/vector4/
     - buttons: https://docs.fivem.net/docs/game-references/controls/

]]

-- main loop
Citizen.CreateThread(function()
    CreateMarker()

    local bobMarker = true
    while (true) do
        Citizen.Wait(0)

        -- enable / disable the bobbing marker above your characters head
        if (IsControlJustReleased(0, 21 --[[ Left Shift ]])) then
            bobMarker = not bobMarker
            TriggerEvent("MarkerManager:Enable", "MMECharMarker", bobMarker)
        end
    end
end)

function CreateMarker()
    -- register a simple marker for parking your vehicle
    TriggerEvent("MarkerManager:Register",
        "MMEParkMarker",                            -- name of the marker (must be individual!)
        100.0,                                      -- view distance of the marker (in units / meters)
        1,                                          -- type id of the marker
        vector3(212.62, -797.9, 29.87),             -- position of the marker as a vector3
        vector3(3, 3, 0.5),                         -- scale of the marker as a vector3
        vector4(255, 0, 0, 255)                     -- color of the marker as a vector4 (Format: RGBA)
    )
    -- add the delete function to the marker
    TriggerEvent("MarkerManager:AddFunction",
        "MMEParkMarker",                            -- name of the marker (needs to be identical to the created marker!)
        "ParkCar",                                  -- the name of the event that should be triggered
        "Press ~INPUT_CONTEXT~ to park your car.",  -- the help text in the top left corner of the screen
        51                                          -- the button to press to execute the function
    )

    -- register a simple marker for spawning a vehicle
    TriggerEvent("MarkerManager:Register",
        "MMESpawnMarker",                           -- name of the marker (must be individual!)
        100.0,                                      -- view distance of the marker (in units / meters)
        1,                                          -- type id of the marker
        vector3(229.63, -799.26, 29.57),            -- position of the marker as a vector3
        vector3(3, 3, 0.5),                         -- scale of the marker as a vector3
        vector4(0, 255, 0, 255)                     -- color of the marker as a vector4 (Format: RGBA)
    )
    -- add the spawn function to the marker
    TriggerEvent("MarkerManager:AddFunction",
        "MMESpawnMarker",                           -- name of the marker (needs to be identical to the created marker!)
        "SpawnCar",                                 -- the name of the event that should be triggered
        "Press ~INPUT_CONTEXT~ to spawn a car.",    -- the help text in the top left corner of the screen
        51                                          -- the button to press to execute the function
    )

    -- register a simple marker for teleporting the player (on enter)
    TriggerEvent("MarkerManager:Register",
        "MMETeleportMarker",
        50.0,
        1,
        vector3(213.71, -809.16, 30.01),
        vector3(3, 3, 0.5),
        vector4(255, 255, 0, 255)
    )
    -- add the teleport function to the marker
    TriggerEvent("MarkerManager:AddEnterFunction",
        "MMETeleportMarker",
        "TeleportPlayer"
    )

    -- register a simple marker for showing the player an exit message (on exit)
    TriggerEvent("MarkerManager:Register",
        "MMEPlayerExitArea",
        50.0,
        1,
        vector3(230.28, -811.99, 29.43),
        vector3(3, 3, 0.5),
        vector4(0, 0, 255, 255)
    )
    -- add the teleport function to the marker
    TriggerEvent("MarkerManager:AddExitFunction",
        "MMEPlayerExitArea",
        "PlayerExitedArea"
    )

    -- wait for player spawn
    Citizen.Wait(5000)

    -- register an advanced marker that hovers over the player
    TriggerEvent("MarkerManager:RegisterAdvanced",
        "MMECharMarker",                            -- name of the marker (must be individual!)
        100.0,                                      -- view distance of the marker (in meters)
        0,                                          -- type id of the marker
        vector3(0, 0, 0),                           -- position of the marker as a vector3
        vector3(0, 0, 0),                           -- rotation of the marker as a vector3
        vector3(0.25, 0.25, 0.25),                  -- scale of the marker as a vector3
        vector4(255, 255, 255, 255),                -- color of the marker as a vector4 (Format: RGBA)
        true,                                       -- bob up and down set to true
        false,                                      -- should the marker face the camera?
        false                                       -- should the marker be rotating?
    )
    -- attach the marker to the player ped
    TriggerEvent("MarkerManager:AttachToEntity",
        "MMECharMarker",                            -- the name of the marker (needs to be identical to the created marker!)
        PlayerPedId(),                              -- the id of the entity
        vector3(0, 0, 1.5)                          -- the offset in relations to the entity as a vector3
    )
end

-- event handler for the "ParkCar" function
AddEventHandler("ParkCar", function()
    local playerPed = PlayerPedId()
    local vehicle = GetVehiclePedIsIn(playerPed)

    if (vehicle ~= 0) then
        SetEntityAsMissionEntity(vehicle)
        DeleteVehicle(vehicle)
    end
end)

-- event handler for the "SpawnCar" function
AddEventHandler("SpawnCar", function()
    local playerPed = PlayerPedId()
    local coords    = GetEntityCoords(playerPed, true)
    local head      = GetEntityHeading(playerPed)

    local model = `banshee`
    RequestModel(model)
    while not HasModelLoaded(model) do
        Citizen.Wait(1)
    end
    local vehicle = CreateVehicle(model, 229.63, -799.26, 29.57, 156, true, false)
    SetModelAsNoLongerNeeded(model)
    SetVehicleOnGroundProperly(vehicle)

    SetPedIntoVehicle(playerPed, vehicle, -1)
    SetVehicleEngineOn(vehicle, true, true)
end)

-- event handler for the "TeleportPlayer" function
AddEventHandler("TeleportPlayer", function()
    local playerPed = PlayerPedId()

    SetEntityCoords(PlayerPedId(), 213.98, -808.8, 33.92)
end)

-- event handler for the "PlayerExitedArea" function
AddEventHandler("PlayerExitedArea", function()
    SetNotificationTextEntry('STRING')
    AddTextComponentSubstringPlayerName("Player left marker!")
    DrawNotification(false, true)
end)

-- event handler for removing all markers when the resource stops
AddEventHandler("onResourceStop", function(resName)
    if (resName == GetCurrentResourceName()) then
        TriggerEvent("MarkerManager:Delete", "MMEParkMarker")
        TriggerEvent("MarkerManager:Delete", "MMESpawnMarker")
        TriggerEvent("MarkerManager:Delete", "MMECharMarker")
        TriggerEvent("MarkerManager:Delete", "MMETeleportMarker")
    end
end)