Inicio › Documentación › Ubicaciones personalizadas · origen_ilegalv2

Ubicaciones personalizadas · origen_ilegalv2

Config.Locations.Types define todos los tipos de ubicación que un líder de banda puede colocar en el mapa desde el panel de gestión (stashes, garajes, vestuarios, puntos de depósito bancario, mesas de gestión…). Puedes añadir tus propios tipos de ubicación ampliando esta tabla, sin editar el núcleo.

Cada tipo controla:

Dónde añadir tipos personalizados

Añade nuevas entradas dentro de Config.Locations.Types en 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,
        },
    },
}

La clave (armory en el ejemplo) es el locationType que se usa internamente. Es el valor que se guarda en la base de datos para cada punto colocado.

Campos del tipo

Campo Tipo Obligatorio Descripción
label string sí Texto mostrado en el aviso de interacción. Puede ser una cadena simple o una clave de idioma (por ejemplo, locations.types.armory.label).
default boolean sí Si es true, el núcleo gestiona el tipo (stash, garaje, vestuario, banco, gestión). Pon false para los tipos personalizados que definen su propio onInteract.
requiredPermission string | nil sí Permiso de rango necesario para interactuar con un punto colocado. Usa nil para permitirlo a cualquier miembro.
blip table sí Configuración del blip del minimapa (ver abajo).
marker table sí Configuración del marker 3D del mundo (ver abajo).
onInteract function no Obligatorio para los tipos personalizados (default = false). Se llama en el cliente cuando un miembro interactúa con el punto. Recibe (gangData, locationId, locationData).
placement_preview table no Solo lo usan tipos especiales que necesitan una vista previa en el mundo mientras se colocan (por ejemplo, garage muestra un vehículo para elegir la orientación).

blip

Campo Tipo Descripción
enabled boolean Muestra el blip en el minimapa.
sprite number ID del sprite de blip de GTA.
color number ID del color de blip de GTA.
scale number Tamaño del blip.

marker

Campo Tipo Descripción
type number ID del tipo de marker; consulta la referencia de markers de FiveM.
offset { x, y, z } Desplazamiento respecto a la coordenada base. El alias heredado offsetZ (float) sigue aceptándose.
scale { x, y, z } Tamaño del marker por eje.
color { r, g, b, a } RGBA 0–255.
bobUpAndDown boolean Animación de balanceo.
faceCamera boolean Mira siempre a la cámara.
rotationOrder number Orden de los ejes para la rotación (por defecto 2).
rotate boolean Gira sobre su eje.

Cómo funciona la interacción de un tipo personalizado

Cuando default = false, el núcleo llama a la función onInteract definida directamente en la configuración del tipo. Esta función se ejecuta en el cliente y recibe tres argumentos:

Argumento Tipo Descripción
gangData table Los datos de la banda del jugador (id, nombre, miembros, rangos, etc.).
locationId string El ID único del punto colocado (por ejemplo, gang_ballas_armory_1).
locationData table Datos en bruto de la ubicación, incluidas las coordenadas (x, y, z, h) y el type.

La validación del permiso (requiredPermission) la gestiona el núcleo antes de llamar a onInteract. Si el miembro no tiene el permiso necesario, la interacción se bloquea en silencio y onInteract nunca se ejecuta.

onInteract se ejecuta en el cliente. Para ejecutar lógica del lado servidor (abrir un inventario, dar objetos, etc.), lanza un evento de servidor desde dentro de la función.

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 los handlers de servidor personalizados dentro de custom/server/ para que las actualizaciones del núcleo no sobrescriban tu lógica.

Sistema de permisos

requiredPermission se corresponde directamente con los flags de permiso de rango definidos en Config.Gang.DefaultRanks (config/gangs.lua). Cuando un miembro intenta interactuar con un punto colocado, el núcleo comprueba:

lua
gang:hasPermission(identifier, location.requiredPermission)

Si devuelve false, la interacción se bloquea en silencio.

Añadir tu propio flag de permiso

  1. Define el flag en cada rango por defecto que deba recibirlo:

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

  2. Haz referencia a él desde tu tipo de ubicación:

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

  3. Restricción de colocación (opcional): para restringir quién puede colocar el punto (no solo interactuar), el panel de gestión reutiliza el permiso estándar manage_locations para todos los tipos. No hace falta configuración adicional.

Todo rango que deba poder ver o usar el nuevo permiso debe tener el flag definido explícitamente. Los flags que faltan valen false por defecto.

Los miembros también pueden editar los permisos de rango en tiempo de ejecución desde el panel de banda (si tienen manage_ranks). Cualquier clave de permiso declarada en Config.Gang.DefaultRanks se lista allí automáticamente.

Ejemplo 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 el recurso. El nuevo tipo Armory aparece en el selector de colocación de ubicaciones para cualquier rango con manage_locations, y solo los miembros con access_armory pueden interactuar con los puntos colocados.