GW-Drag-lib

GW Draggable Lib — Guide complet (GitBook)

Ce guide explique comment installer, configurer et utiliser la librairie de drag & drop d’objets, l’UI intégrée (steps + contrôles), ainsi que les fonctions utilitaires d’animation et d’effets. Le but est qu’un débutant puisse tout utiliser rapidement.

Présentation

• Déplacement d’objets 3D à la souris avec surbrillance et rotation à la molette

• Interactions “drag → drop” validées par modèles, avec distance et tolérance

• UI “Étapes” (steps) à gauche et “Contrôles” en bas à gauche

• Timer d’étapes (optionnel)

• Localisation (FR/EN/ES)

• Affichage d’un label près du curseur (configurable)

• Fonctions utilitaires prêtes à l’emploi (shake, move, fade, rotation smooth)

• Sécurité/robustesse: auto-stop si le joueur meurt/ragdoll/chute libre, callbacks encapsulés en pcall

Limitations actuelles

• Drag d’un seul objet à la fois (pas de “multi-drag” simultané). Vous pouvez toutefois afficher/spawner plusieurs objets à manipuler dans une session.

Installation

1. Placer la ressource dans votre serveur:

• Dossier: resources/[LOCK]/gw-draggable-lib

1. Manifeste

• fxmanifest.lua inclut déjà:

  • client_scripts: config.lua, functions.lua, Draggable.lua, exemple.lua

  • ui_page + files pour l’UI

1. Démarrer la ressource

• ensure gw-draggable-lib dans votre server.cfg

Configuration globale (config.lua)

• Debug et couleur de surbrillance:

Config.Debug = false
Config.DrawOutlineColor = { r = 0, g = 170, b = 255, a = 255 }

• Constantes du drag:

Config.CONSTANTS = {
  MAX_DRAG_DISTANCE = 2.5,             -- distance max devant le joueur où l’objet suit
  ROTATION_SPEED = 2.0,                 -- vitesse de rotation par “tick”
  MOUSE_MOVE_THRESHOLD = 0.002,         -- seuil de déplacement souris
  DROP_PROXIMITY_THRESHOLD = 0.5,       -- rayon pour fallback de cible la plus proche
  DROP_VALIDATE_MAX_DISTANCE = 1.25,    -- distance drag/cible requise pour valider le drop
  CONTROLS = {
    DISABLED = { 140,141,142,30,31,32,33,1,2,174,175,199,200 },
    MOUSE_X = 239, MOUSE_Y = 240, ATTACK = 24,
    SCROLL_UP = 15, SCROLL_DOWN = 14, INTERACT = 38,
    ROTATE_LEFT = 174, ROTATE_RIGHT = 175
  },
  MOUSE_SPRITES = { DEFAULT = 1, HAND_OPEN = 3, HAND_CLOSED = 4 }
}

• Caméra:

Config.Camera = {
  enableByDefault = true,
  defaultFov = 45.0,
  offset = vector3(0.0, 0.0, 1.0),
  pointOffset = vector3(0.0, 0.0, 0.5),
  transitionMs = 600
}

• UI “Steps”:

Config.StepsUI = {
  enabled = true,
  title = "Étapes",
  autoHideOnComplete = false   -- recommandé: false si vous déclenchez vous-même l’arrêt juste après
}

• Locale:

Config.Locale = 'fr' -- fr, en, es

• Label du nom sous le curseur:

Config.Label = {
  enabled = true,
  scale = 0.35,
  color = { r = 255, g = 255, b = 255, a = 230 },
  font = 4,
  offset = { x = 0.0, y = -0.03 },
  background = {
    enabled = true,
    color = { r = 12, g = 15, b = 20, a = 160 },
    padding = { x = 0.008, y = 0.016 },
    radius = 0.006
  }
}

• Noms de modèles (affichés au survol) centralisés:

Config.props = {
  { model = 'prop_food_cb_tray_03', name = 'Plateau' },
  { model = 'prop_recyclebin_03_a', name = 'Poubelle' }
}

API Client

1) Draggable:Register(config)

Enregistre une “session” avec:

• props: objets à spawner

• interactions: règles “drag → drop” et callbacks

• steps: liste d’étapes (UI)

• stepsTitle (optionnel)

• stepsMaxTimeSeconds ou stepsMaxTimeMs (optionnels)

• onTimeout (optionnel)

• onStop (optionnel)

Exemple:

local config = {
  props = {
    { model = 'prop_food_cb_tray_03', coords = vector3(...), rotation = vector3(...) },
    { model = 'prop_recyclebin_03_a', coords = vector3(...), rotation = vector3(...) }
  },
  interactions = {
    {
      stepId = 'placer_plateau',        -- optionnel (cocher une étape quand valide)
      drag = 'prop_food_cb_tray_03',    -- string modèle ou hash ou liste
      drop = 'prop_recyclebin_03_a',    -- string modèle ou hash ou liste
      maxDistance = 1.0,                -- override local de la distance de validation
      callback = function(draggingProp, dropTarget)
        -- exemple d’animation:
        MoveEntitySmoothly(draggingProp, GetEntityCoords(dropTarget) + vector3(0,0,1.2), 300)
        Citizen.Wait(300)
        SetRotationSmoothly(draggingProp, GetEntityRotation(dropTarget) - vector3(0,140,0), 300)
        Shakeprops(draggingProp, 1000, 0.06, 0.07)
        Citizen.Wait(500)
        DeleteEntityFade(draggingProp, 500)
      end
    }
  },
  stepsTitle = 'Tutoriel Drag & Drop',
  steps = {
    { id = 'placer_plateau', title = 'Placer le plateau', description = 'Glisser le plateau sur la poubelle' }
  },
  stepsMaxTimeSeconds = 25,
  onTimeout = function()
    BeginTextCommandThefeedPost("STRING")
    AddTextComponentSubstringPlayerName("Temps écoulé, interaction terminée")
    EndTextCommandThefeedPostTicker(false, true)
  end,
  onStop = function()
    BeginTextCommandThefeedPost("STRING")
    AddTextComponentSubstringPlayerName("Interaction terminée")
    EndTextCommandThefeedPostTicker(false, true)
  end
}

Draggable:Register(config)

2) Draggable:Start([targetOrOptions])

Démarre l’interaction.

• Paramètre facultatif:

  • Entité à focus (handle)

  • Coords à focus (vector3)

  • Table d’options: { focusEntity=..., focusCoords=..., enableCamera=true/false, camera={...} }

Exemples:

-- simple
Draggable:Start()

-- focus coordonnées (2.2m devant le joueur)
local ped = PlayerPedId()
local p = GetEntityCoords(ped)
local f = GetEntityForwardVector(ped)
Draggable:Start({ focusCoords = vector3(p.x+f.x*2.2, p.y+f.y*2.2, p.z+0.3), enableCamera = true })

3) Draggable:Stop()

Arrête l’interaction proprement:

• Restaure collision/Freeze, détruit les props de la session

• Masque l’UI “Steps” et la barre “Contrôles”

• Appelle onStop si défini

4) Draggable:SetCustomCamera(camHandle)

Spécifie une caméra custom à utiliser pour le raycast souris.

Structure d’une session

• props[]:

  • model: string (nom de modèle) ou hash

  • coords: vector3

  • rotation: vector3

  • name (optionnel): si non fourni ici, le nom est récupéré dans Config.props

• interactions[]:

  • drag: string/hash ou table de modèles autorisés

  • drop: string/hash ou table de modèles cibles

  • stepId (optionnel): id d’étape à cocher si drop valide

  • maxDistance (optionnel): distance de validation “drag vs drop”

  • callback(draggingProp, dropTarget): appelé quand la règle est validée

• steps[]:

  • id, title, description

• stepsMaxTimeSeconds / stepsMaxTimeMs (optionnels)

  • si non complété à temps: onTimeout() + stop

UI intégrée

• Panneau “Étapes” (gauche) avec liste des steps

• Barre “Contrôles” (bas gauche) avec:

  • Souris G.: saisir/lâcher

  • Molette: rotation

  • ESC: quitter

Note: lorsque toutes les steps sont cochées, l’UI se masque (selon config et flux). Si vous arrêtez juste après, l’UI se fermera immédiatement.

Contrôles par défaut

• Clic gauche (ATTACK): saisir/lâcher l’objet

• Molette haut/bas: rotation Z +/- pendant le drag

• ESC: quitter sans valider

Astuce: ajustez ROTATION_SPEED dans Config.CONSTANTS pour une rotation plus lente/rapide.

Validation des drops

• Matching par hash modèle: drag et drop acceptent noms ou hashes (ou listes)

• Si le raycast sous la souris n’attrape pas la bonne cible, fallback sur la cible valide la plus proche dans un rayon (DROP_PROXIMITY_THRESHOLD)

• Distance de validation entre l’objet lâché et la cible (DROP_VALIDATE_MAX_DISTANCE global ou interaction.maxDistance)

• Si les conditions sont OK:

  • stepId (si défini) est coché

  • puis callback(draggingProp, dropTarget) est exécuté (protégé par pcall)

Fonctions utilitaires (animations/effets)

Disponibles côté client (via functions.lua). Signatures et exemples:

• MoveEntitySmoothly(entity, targetCoords, duration)

  • Déplace en douceur vers targetCoords en duration ms

  • Exemple:

    MoveEntitySmoothly(obj, GetEntityCoords(target) + vector3(0,0,1.2), 300)

• SetRotationSmoothly(entity, targetRotation, duration)

  • Fait pivoter progressivement jusqu’à targetRotation

  • Exemple:

    SetRotationSmoothly(obj, GetEntityRotation(target) - vector3(0,140,0), 300)

• Shakeprops(entity, duration?, intensity?, smoothness?)

  • “Tremblement” doux d’un objet (par défaut 2500ms, intensité 0.03, lissage 0.05)

  • Exemple:

    Shakeprops(obj, 1000, 0.06, 0.07)

• DeleteEntityFade(entity, duration?)

  • Fade out puis suppression de l’entité (par défaut 1000ms)

• Helpers math:

  • Normalize(v), CrossProduct(v1, v2), DotProduct(v1, v2), LerpColor(c1, c2, t), CT(table)

Localisation

• Définir Config.Locale ('fr', 'en', 'es')

• Les libellés UI (steps title, contrôles) suivent cette locale

Bonnes pratiques

• Définissez Config.props pour nommer vos modèles une seule fois; vous n’aurez pas à répéter name dans chaque session

• Ajustez DROP_VALIDATE_MAX_DISTANCE si vos modèles sont gros/petits pour éviter des validations “trop faciles” ou “impossibles”

• Dans vos callbacks, utilisez les utilitaires MoveEntitySmoothly, SetRotationSmoothly, Shakeprops, DeleteEntityFade pour donner du pep’s

• Pour plusieurs interactions, utilisez des stepId différents pour guider l’utilisateur étape par étape

Exemple de bout en bout

-- Commande pour démarrer (exemple)
RegisterCommand('drag_start', function()
  local ped = PlayerPedId()
  local p = GetEntityCoords(ped)
  local f = GetEntityForwardVector(ped)
  local heading = GetEntityHeading(ped)

  local config = {
    props = {
      {
        model = 'prop_food_cb_tray_03',
        coords = vector3(p.x + f.x*1.8, p.y + f.y*1.8, p.z - 0.98),
        rotation = vector3(0.0, 0.0, heading)
      },
      {
        model = 'prop_recyclebin_03_a',
        coords = vector3(p.x + f.x*2.6, p.y + f.y*2.6, p.z - 0.98),
        rotation = vector3(0.0, 0.0, heading)
      }
    },
    interactions = {
      {
        stepId = 'placer_plateau',
        drag = 'prop_food_cb_tray_03',
        drop = 'prop_recyclebin_03_a',
        maxDistance = 1.0,
        callback = function(draggingProp, dropTarget)
          MoveEntitySmoothly(draggingProp, GetEntityCoords(dropTarget) + vector3(0,0,1.2), 300)
          Citizen.Wait(300)
          SetRotationSmoothly(draggingProp, GetEntityRotation(dropTarget) - vector3(0,140,0), 300)
          Shakeprops(draggingProp, 1000, 0.06, 0.07)
          Citizen.Wait(500)
          DeleteEntityFade(draggingProp, 500)
        end
      }
    },
    stepsTitle = 'Tutoriel Drag & Drop',
    steps = {
      { id = 'placer_plateau', title = 'Placer le plateau', description = 'Glisser le plateau sur la poubelle' }
    },
    stepsMaxTimeSeconds = 25
  }

  Draggable:Register(config)

  local focus = vector3(p.x + f.x*2.2, p.y + f.y*2.2, p.z + 0.3)
  Draggable:Start({ focusCoords = focus, enableCamera = true })
end, false)

RegisterCommand('drag_stop', function()
  Draggable:Stop()
end, false)

Dépannage

• Le menu pause s’ouvre avec ESC

  • Config.CONSTANTS.CONTROLS.DISABLED inclut déjà 199, 200. Assurez-vous que Config.lua est bien chargé en premier (fxmanifest).

• Le label du nom ne s’affiche pas

  • Assurez-vous d’avoir un name dans Config.props pour ce modèle (ou directement dans propInfo.name).

• Le drop valide trop loin / trop près

  • Ajustez DROP_VALIDATE_MAX_DISTANCE (global) ou interaction.maxDistance (local).

• Les steps ne se cochent pas

  • Vérifiez stepId dans interaction correspond exactement à l’id d’une step dans steps.

  • Vérifiez les modèles drag/drop (noms GTAV corrects).