Início › Documentação › Localizações personalizadas · origen_ilegalv2

Localizações personalizadas · origen_ilegalv2

Config.Locations.Types define todos os tipos de localização que um líder de gangue pode colocar no mapa a partir do painel de gestão (stashes, garagens, vestiários, pontos de depósito bancário, secretárias de gestão…). Podes adicionar os teus próprios tipos de localização ampliando esta tabela, sem editar o núcleo.

Cada tipo controla:

Onde adicionar tipos personalizados

Adiciona novas entradas dentro de Config.Locations.Types em config/locations.lua:

luaconfig/locations.lua
Config.Locations = {
    DrawDistance       = 50.0,
    InteractDistance   = 1.5,
    MarkerDrawDistance = 15.0,
 
    Types = {
        stash = { --[[ ... ]] },
        garage = { --[[ ... ]] },
 
        -- your custom type
        armory = {
            label              = 'Open gang armory',
            default            = false,
            requiredPermission = 'access_armory',
 
            blip = {
                enabled = false,
                sprite  = 110,
                color   = 1,
                scale   = 0.7,
            },
 
            marker = {
                type          = 22,
                offset        = { x = 0.0, y = 0.0, z = 1.0 },
                scale         = { x = 0.25, y = 0.25, z = 0.25 },
                color         = { r = 255, g = 0, b = 0, a = 255 },
                bobUpAndDown  = true,
                faceCamera    = true,
                rotationOrder = 2,
                rotate        = false,
            },
 
            onInteract = function(gangData, locationId, locationData)
                -- client-side logic here
                TriggerServerEvent('my_resource:openArmory', gangData.id)
            end,
        },
    },
}

A chave (armory no exemplo) é o locationType usado internamente. É o valor guardado na base de dados para cada ponto colocado.

Campos do tipo

Campo Tipo Obrigatório Descrição
label string sim Texto mostrado no aviso de interação. Pode ser uma string simples ou uma chave de idioma (por exemplo, locations.types.armory.label).
default boolean sim Se for true, o núcleo trata o tipo (stash, garagem, vestiário, banco, gestão). Define false para os tipos personalizados que definem o seu próprio onInteract.
requiredPermission string | nil sim Permissão de cargo necessária para interagir com um ponto colocado. Usa nil para permitir a qualquer membro.
blip table sim Configuração do blip do minimapa (ver abaixo).
marker table sim Configuração do marker 3D do mundo (ver abaixo).
onInteract function não Obrigatório para os tipos personalizados (default = false). Chamada no cliente quando um membro interage com o ponto. Recebe (gangData, locationId, locationData).
placement_preview table não Usado apenas por tipos especiais que precisam de uma pré-visualização no mundo durante a colocação (por exemplo, garage mostra um veículo para escolher a orientação).

blip

Campo Tipo Descrição
enabled boolean Mostra o blip no minimapa.
sprite number ID do sprite de blip do GTA.
color number ID da cor de blip do GTA.
scale number Tamanho do blip.

marker

Campo Tipo Descrição
type number ID do tipo de marker; consulta a referência de markers do FiveM.
offset { x, y, z } Deslocamento em relação à coordenada base. O alias antigo offsetZ (float) continua a ser aceite.
scale { x, y, z } Tamanho do marker por eixo.
color { r, g, b, a } RGBA 0–255.
bobUpAndDown boolean Animação de balanço.
faceCamera boolean Olha sempre para a câmara.
rotationOrder number Ordem dos eixos para a rotação (por omissão 2).
rotate boolean Gira sobre o seu eixo.

Como funciona a interação de um tipo personalizado

Quando default = false, o núcleo chama a função onInteract definida diretamente na configuração do tipo. Esta função é executada no cliente e recebe três argumentos:

Argumento Tipo Descrição
gangData table Os dados da gangue do jogador (id, nome, membros, cargos, etc.).
locationId string O ID único do ponto colocado (por exemplo, gang_ballas_armory_1).
locationData table Dados em bruto da localização, incluindo as coordenadas (x, y, z, h) e o type.

A validação da permissão (requiredPermission) é feita pelo núcleo antes de chamar onInteract. Se o membro não tiver a permissão necessária, a interação é bloqueada em silêncio e onInteract nunca é executada.

onInteract é executada no cliente. Para executar lógica do lado do servidor (abrir um inventário, dar itens, etc.), aciona um evento de servidor a partir de dentro da função.

luaconfig/locations.lua — onInteract example
onInteract = function(gangData, locationId, locationData)
    -- trigger your own server event from here
    TriggerServerEvent('my_resource:openArmory', gangData.id)
end,
luacustom/server/my_armory.lua — server handler
RegisterNetEvent('my_resource:openArmory', function(gangId)
    local src = source
    -- your server-side logic here
    exports.ox_inventory:openInventory(src, {
        type = 'shop',
        id   = 'gang_armory_' .. gangId,
    })
end)

Coloca os handlers de servidor personalizados dentro de custom/server/ para que as atualizações do núcleo não substituam a tua lógica.

Sistema de permissões

requiredPermission corresponde diretamente às flags de permissão de cargo definidas em Config.Gang.DefaultRanks (config/gangs.lua). Quando um membro tenta interagir com um ponto colocado, o núcleo verifica:

lua
gang:hasPermission(identifier, location.requiredPermission)

Se devolver false, a interação é bloqueada em silêncio.

Adicionar a tua própria flag de permissão

  1. Define a flag em cada cargo por omissão que a deva receber:

    luaconfig/gangs.lua
    DefaultRanks = {
    {
        id   = 1,
        name = "Leader",
        permissions = {
            -- ... existing flags ...
            access_armory = true,
        },
    },
    {
        id   = 3,
        name = "Member",
        permissions = {
            access_armory = false,
        },
    },
},

  2. Referencia-a a partir do teu tipo de localização:

    lua
    armory = {
    requiredPermission = 'access_armory',
    -- ...
},

  3. Restrição de colocação (opcional): para restringir quem pode colocar o ponto (não apenas interagir), o painel de gestão reutiliza a permissão padrão manage_locations para todos os tipos. Não é preciso configuração adicional.

Todos os cargos que devam poder ver ou usar a nova permissão têm de ter a flag definida explicitamente. As flags em falta valem false por omissão.

Os membros também podem editar as permissões dos cargos em tempo de execução a partir do painel da gangue (se tiverem manage_ranks). Qualquer chave de permissão declarada em Config.Gang.DefaultRanks é listada aí automaticamente.

Exemplo completo — tipo armory

luaconfig/locations.lua
armory = {
    label              = 'locations.types.armory.label',
    default            = false,
    requiredPermission = 'access_armory',
 
    blip = {
        enabled = true,
        sprite  = 110,
        color   = 1,
        scale   = 0.7,
    },
 
    marker = {
        type          = 22,
        offset        = { x = 0.0, y = 0.0, z = 1.0 },
        scale         = { x = 0.3, y = 0.3, z = 0.3 },
        color         = { r = 255, g = 50, b = 50, a = 200 },
        bobUpAndDown  = true,
        faceCamera    = true,
        rotationOrder = 2,
        rotate        = false,
    },
 
    onInteract = function(gangData, locationId, locationData)
        TriggerServerEvent('my_resource:openArmory', gangData.id)
    end,
},
luaconfig/gangs.lua — DefaultRanks
-- Leader + Co-Leader:
access_armory = true,
-- Member + Recruit:
access_armory = false,
luacustom/server/my_armory.lua
RegisterNetEvent('my_resource:openArmory', function(gangId)
    local src = source
    exports.ox_inventory:openInventory(src, {
        type = 'shop',
        id   = 'gang_armory_' .. gangId,
    })
end)

Reinicia o recurso. O novo tipo Armory aparece no seletor de colocação de localizações para qualquer cargo com manage_locations, e apenas os membros com access_armory podem interagir com os pontos colocados.