Accueil › Documentation › Lieux personnalisés · origen_ilegalv2

Lieux personnalisés · origen_ilegalv2

Config.Locations.Types définit tous les types d’emplacement qu’un leader de gang peut placer sur la carte via le panneau de gestion (stashes, garages, vestiaires, points de dépôt bancaire, bureaux de gestion…). Tu peux ajouter tes propres types d’emplacement en étendant cette table, sans modifier le cœur.

Chaque type contrôle :

L’apparence de son blip et de son marker 3D.
La permission dont un membre a besoin pour interagir avec lui.
S’il s’agit d’un type par défaut (généré automatiquement pour les nouveaux gangs).

Où ajouter des types personnalisés

Ajoute de nouvelles entrées dans Config.Locations.Types dans 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 clé (armory dans l’exemple) est le locationType utilisé en interne. C’est la valeur enregistrée en base de données pour chaque point placé.

Champs du type

Champ	Type	Obligatoire	Description
`label`	`string`	oui	Texte affiché dans l’invite d’interaction. Peut être une simple chaîne ou une clé de langue (par exemple `locations.types.armory.label`).
`default`	`boolean`	oui	Si `true`, le type est géré par le cœur (stash, garage, vestiaire, banque, gestion). Mets `false` pour les types personnalisés qui définissent leur propre `onInteract`.
`requiredPermission`	`string` \| `nil`	oui	Permission de grade requise pour interagir avec un point placé. Utilise `nil` pour l’autoriser à tout membre.
`blip`	`table`	oui	Configuration du blip de la minicarte (voir ci-dessous).
`marker`	`table`	oui	Configuration du marker 3D du monde (voir ci-dessous).
`onInteract`	`function`	non	Obligatoire pour les types personnalisés (`default = false`). Appelée côté client lorsqu’un membre interagit avec le point. Reçoit `(gangData, locationId, locationData)`.
`placement_preview`	`table`	non	Utilisé uniquement par les types spéciaux qui ont besoin d’un aperçu dans le monde pendant le placement (par exemple, `garage` affiche un véhicule pour choisir l’orientation).

`blip`

Champ	Type	Description
`enabled`	`boolean`	Affiche le blip sur la minicarte.
`sprite`	`number`	ID du sprite de blip GTA.
`color`	`number`	ID de la couleur de blip GTA.
`scale`	`number`	Taille du blip.

`marker`

Champ	Type	Description
`type`	`number`	ID du type de marker ; voir la référence des markers FiveM.
`offset`	`{ x, y, z }`	Décalage par rapport à la coordonnée de base. L’ancien alias `offsetZ` (float) reste accepté.
`scale`	`{ x, y, z }`	Taille du marker par axe.
`color`	`{ r, g, b, a }`	RGBA 0–255.
`bobUpAndDown`	`boolean`	Animation de balancement.
`faceCamera`	`boolean`	Fait toujours face à la caméra.
`rotationOrder`	`number`	Ordre des axes pour la rotation (par défaut `2`).
`rotate`	`boolean`	Tourne sur son axe.

Comment fonctionne l’interaction d’un type personnalisé

Lorsque default = false, le cœur appelle la fonction onInteract définie directement dans la configuration du type. Cette fonction s’exécute côté client et reçoit trois arguments :

Argument	Type	Description
`gangData`	`table`	Les données du gang du joueur (id, nom, membres, grades, etc.).
`locationId`	`string`	L’ID unique du point placé (par exemple `gang_ballas_armory_1`).
`locationData`	`table`	Données brutes de l’emplacement, dont les coordonnées (`x`, `y`, `z`, `h`) et le `type`.

La validation de la permission (requiredPermission) est gérée par le cœur avant l’appel à onInteract. Si le membre n’a pas la permission requise, l’interaction est bloquée en silence et onInteract ne s’exécute jamais.

onInteract s’exécute côté client. Pour exécuter une logique côté serveur (ouvrir un inventaire, donner des items, etc.), déclenche un événement serveur depuis la fonction.

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)

Place les handlers serveur personnalisés dans custom/server/ afin que les mises à jour du cœur n’écrasent pas ta logique.

Système de permissions

requiredPermission correspond directement aux flags de permission de grade définis dans Config.Gang.DefaultRanks (config/gangs.lua). Lorsqu’un membre tente d’interagir avec un point placé, le cœur vérifie :

lua

gang:hasPermission(identifier, location.requiredPermission)

Si cela renvoie false, l’interaction est bloquée en silence.

Ajouter ton propre flag de permission

Définis le flag dans chaque grade par défaut qui doit le recevoir :

luaconfig/gangs.lua

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

Référence-le depuis ton type d’emplacement :

lua

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

Restriction de placement (facultatif) : pour restreindre qui peut placer le point (et pas seulement interagir), le panneau de gestion réutilise la permission standard manage_locations pour tous les types. Aucune configuration supplémentaire n’est nécessaire.

Chaque grade qui doit pouvoir voir ou utiliser la nouvelle permission doit avoir le flag défini explicitement. Les flags manquants valent false par défaut.

Les membres peuvent aussi modifier les permissions de grade à l’exécution depuis le panneau de gang (s’ils ont manage_ranks). Toute clé de permission déclarée dans Config.Gang.DefaultRanks y est listée automatiquement.

Exemple complet — type 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)

Redémarre la ressource. Le nouveau type Armory apparaît dans le sélecteur de placement d’emplacements pour tout grade disposant de manage_locations, et seuls les membres disposant de access_armory peuvent interagir avec les points placés.