Adding Cayo Perico to a FiveM server, and to its minimap

#Step 1: the game build

sv_enforceGameBuild 2189   # or any newer build

Build 2189 is the Cayo Perico Heist update. Newer builds include it too. Changing the enforced build makes every player download that game version’s data on their next join — see game builds and DLC.

#Step 2: loading the island

local ISLAND = vector2(4840.0, -5174.0)
local RANGE = 2000.0
local loaded = false

local function setIsland(on)
    SetIslandHopperEnabled('HeistIsland', on)
    SetToggleMinimapHeistIsland(on)
    SetAiGlobalPathNodesType(on and 1 or 0)
    LoadGlobalWaterType(on and 1 or 0)
    SetScenarioGroupEnabled('Heist_Island_Peds', on)
    loaded = on
end

CreateThread(function()
    while true do
        local p = GetEntityCoords(PlayerPedId())
        local near = #(vector2(p.x, p.y) - ISLAND) < RANGE
        if near ~= loaded then setIsland(near) end
        Wait(2000)
    end
end)

Switching by distance matters because the island’s water map and path nodes replace the mainland’s. With them active everywhere, AI traffic and water behave oddly on the mainland.

#The island on the minimap

SetToggleMinimapHeistIsland(true) swaps in the minimap data that includes Cayo Perico. The island sits far south-east of Los Santos, so on the pause map it appears in the ocean area — the same area many custom minimaps use for branding. If you use a custom minimap, check your branding does not overlap the island’s position; see branding your server map.

The island draws from its own Scaleform file rather than the mainland tiles, so a custom minimap replacement does not change it: the radar switches from your art to the stock Rockstar island the moment a player arrives. The matching island map is sold here as a Cayo Perico minimap add-on — the same palette, the same roads and labels, as a second drop-in resource.

#Roleplay uses

• Cartel and smuggling storylines with boat and plane runs.
• A luxury resort, private events or a VIP area.
• Military or survival scenarios in the jungle.
• Drug growing and processing locations far from the city.