Interact system

1. 01

   Resource ablegen

   Hol dir das Script aus deinem Tebex-Konto und kopier den Ordner avenida_interact/ auf deinem Server nach resources/[avenida]/.

2. 02

   In der server.cfg aktivieren

   Füg ensure avenida_interact hinzu. Vorher muss nichts anderes starten: Seit 1.1.0 hat die Resource keine Dependencies, die Ladereihenfolge ist also egal.

3. 03

   Deine Defaults setzen

   Öffne config/config.lua und stell ein, was für alle Punkte gilt: Label, Taste, die Distanzen showIcon und canInteract, Icon, Farbe, benannte Farben, die Spawn-Distanz der Peds und Config.Hud für das HUD, das während eines Dialogs ausgeblendet wird.

4. 04

   Demos entfernen

   Die Beispiele in config/entities/, config/peds/ und config/positions/ sind aktiv, solange ihre Dateien da sind. Lösch die, die du nicht willst. Das Manifest globt diese Ordner, mehr musst du nicht anfassen.

5. 05

   Hot Reload testen

   Starte den Server und tipp im Spiel /restart avenida_interact. Die Icons verschwinden und kommen sauber zurück, und die Punkte deiner eigenen Resources bleiben erhalten, ohne dass du deine Session neu startest.

Dein erster Interaktionspunkt in 30 Sekunden

Leg eine `myscript/client.lua` in deiner eigenen Resource an und füg das hier ein. Ein cyanfarbener Marker erscheint ab 30m, der Prompt „E - Hello“ rollt ab 2m aus. Laufen muss dafür nur avenida_interact selbst.

-- myscript/client.lua
exports.avenida_interact:positionRegister({
    coords      = vec3(-265.0, -963.6, 31.2),
    showIcon    = 30.0,           -- marker fades in at 30m
    canInteract = 2.0,            -- label unrolls at 2m
    hintIcon    = 'interact',     -- see the icon list below
    hintColor   = '#22d3ee',      -- hex, or an alias from Config.Colors
    message     = 'Hello',
    bind        = 'E',
    onInteract  = function()
        TriggerEvent('chat:addMessage', { args = { 'Hello, world!' } })
    end,
})

Öffentliche Exports nach Bereich gruppiert. Jede Zeile zeigt die Signatur und was der Export macht, nicht wie er es macht.

Interact Points

• positionRegister

  exports.avenida_interact:positionRegister(cfg) --> id Kopieren

  Registriert einen Punkt auf festen Koordinaten. Nimmt jedes visuelle Feld (hintIcon, hintColor, showIcon, canInteract, offsetZ, blips) plus choices[] für mehrere Tasten auf demselben Punkt. canInteract akzeptiert eine Zahl oder eine Funktion, du kannst den Prompt also an einen Job, ein Item oder einen Cooldown binden. Gibt eine ID zurück.

• pedRegister

  exports.avenida_interact:pedRegister(cfg) --> id Kopieren

  Spawnt einen konfigurierten NPC (Modell, animDict und animName oder ein Scenario, Blip), hängt einen Punkt daran und gibt seinen Index zurück. Der Ped ist unverwundbar, flieht nicht und geht nicht in Ragdoll. Er spawnt und verschwindet wieder im Umkreis von Config.PedSpawnRange, standardmäßig 50m. Setz randomComponents = false bei einem Händler mit festem Namen, sonst sieht jeder Spieler ein anderes Outfit.

• pedRemove

  exports.avenida_interact:pedRemove(idx) Kopieren

  Neu in 1.1.0. Despawnt einen mit pedRegister registrierten Ped und löscht seine Registrierung, damit ein temporärer Questgeber wieder gehen kann, wenn die Quest vorbei ist.

• entityRegister

  exports.avenida_interact:entityRegister(cfg) --> id Kopieren

  Hängt einen Punkt an eine bestehende Entity, die du als cfg.entity übergibst. Unterstützt cfg.bone, um den Prompt an einen Bone statt an das Zentrum der Entity zu hängen. Für alles, was ein anderes Script gespawnt hat: ein Fahrzeug, ein platziertes Prop, ein fallengelassenes Item.

• entityRegisterByHash

  exports.avenida_interact:entityRegisterByHash(hash, cfg) Kopieren

  Passiver Watcher: Die Config gilt für jede Entity dieses Modells, für die schon gestreamten und für die, die später auftauchen. Ein einziger Thread deckt alle registrierten Hashes ab und geht sie alle 5s durch. Genau das willst du für ATMs, Automaten und Türen, statt eine Koordinatenliste zu pflegen.

• entityRemove

  exports.avenida_interact:entityRemove(idx) Kopieren

  Hängt den von entityRegister zurückgegebenen Punkt wieder ab. Die Entity selbst bleibt unangetastet.

• interactCreate

  exports.avenida_interact:interactCreate(cfg) --> id Kopieren

  Punkt zur Laufzeit, nach Bedarf erzeugt und entfernt. Für alles, was nur eine Weile existiert: ein Missionsziel, eine Tasche am Boden, eine Leiche zum Durchsuchen.

• interactRemove

  exports.avenida_interact:interactRemove(id) Kopieren

  Entfernt einen mit interactCreate erzeugten Punkt und seinen Blip, falls er einen deklariert hat.

• unlockLastInteract

  exports.avenida_interact:unlockLastInteract() Kopieren

  Ein Punkt sperrt sich nach der Benutzung selbst, damit eine gehaltene Taste ihn nicht zweimal auslöst. Ruf das am Ende deiner Aktion auf, um ihn wieder freizugeben. Ist der Spieler noch in Reichweite, kommt der Prompt direkt zurück, sonst wartet er, bis der Spieler wieder in Reichweite kommt.

Prompt API

• HandleTextUI

  exports.avenida_interact:HandleTextUI(id, data) --> duiHandler Kopieren

  Erzeugt oder aktualisiert eine eigenständige 3D-Sprechblase, ganz ohne Interaktionspunkt dahinter. Für den Fall, dass du die Sichtbarkeit aus deinem eigenen Thread steuern willst. Gibt den Handler zurück, den du an Draw3DSprite weitergibst.

• Draw3DSprite

  exports.avenida_interact:Draw3DSprite({ duiHandler, coords, maxDistance, hintOnly? }) Kopieren

  Zeichnet die Sprechblase in Weltkoordinaten aus einem Render-Thread, entzerrt anhand des Seitenverhältnisses. Mit hintOnly = true wird nur der Marker gezeichnet, das ist der Zustand, den ein normaler Punkt aus der Ferne zeigt.

• CloseTextUI

  exports.avenida_interact:CloseTextUI(id) Kopieren

  Blendet eine Sprechblase aus, behält ihr DUI aber im Speicher, das erneute Öffnen geht damit ohne Verzögerung.

• RemoveTextUI

  exports.avenida_interact:RemoveTextUI(id) Kopieren

  Entfernt eine Sprechblase endgültig und gibt ihr DUI frei. Nimm das, wenn du weißt, dass sie nicht wiederkommt.

• RemoveTextUIs

  exports.avenida_interact:RemoveTextUIs() Kopieren

  Entfernt alle aktiven Sprechblasen. Beim Stoppen der Resource passiert das automatisch.

• IsDuiVisible

  exports.avenida_interact:IsDuiVisible() --> boolean Kopieren

  Gibt true zurück, solange ein Prompt auf dem Bildschirm ist. Frag den Export ab, damit sich deine eigenen Prompts nicht über eine laufende Interaktion legen.

Key handler

• HandleHoldTextUI

  exports.avenida_interact:HandleHoldTextUI(id, data) --> duiHandler Kopieren

  Die Schicht, auf der die Punkte aufbauen: Sie zeichnet einen Prompt an Coords und überwacht dessen Taste aus einem Manager-Thread, der alle 50ms läuft. data nimmt BindToHold (Control-Index), DistanceHold, Coords, ChoicesUI und ChoicesCtrl für einen Prompt mit mehreren Tasten, onCallback(id) und canInteract(id, dist). Löst beim Tastendruck aus, mit 500ms Debounce, und dein Callback läuft in einem pcall, ein Fehler auf deiner Seite reißt den Prompt also nicht mit runter.

• CloseHoldTextUI

  exports.avenida_interact:CloseHoldTextUI(id) Kopieren

  Blendet den Prompt aus, ohne die Instanz zu zerstören, für einen sauberen Abgang, wenn der Spieler die Zone verlässt.

• RemoveHoldTextUI

  exports.avenida_interact:RemoveHoldTextUI(id) Kopieren

  Zerstört eine Instanz und gibt ihr DUI frei.

• RemoveHoldTextUIs

  exports.avenida_interact:RemoveHoldTextUIs() Kopieren

  Zerstört alle aktiven Instanzen.

Praxisnahe Copy-Paste-Beispiele. In deine eigene Resource kopieren, Werte anpassen, fertig.

exports.avenida_interact:positionRegister({
    coords      = vec3(149.5, -1040.4, 29.4),
    showIcon    = 30.0,
    canInteract = 2.0,
    hintIcon    = 'bank',
    hintColor   = 'blue',
    message     = 'Use the ATM',
    bind        = 'E',
    onInteract  = function()
        TriggerEvent('myserver-banking:openATM')
    end,
    blips = {
        sprite  = 277,
        color   = 2,
        scale   = 0.8,
        text    = 'ATM',
        display = 4,
    },
})

local ATM_PROPS = {
    'prop_atm_01', 'prop_atm_02', 'prop_atm_03', 'prop_fleeca_atm',
}

for _, prop in ipairs(ATM_PROPS) do
    exports.avenida_interact:entityRegisterByHash(prop, {
        canInteract = 1.2,
        offsetZ     = 1.0,
        hintIcon    = 'bank',
        hintColor   = 'blue',
        choices = {
            {
                bind       = 'E',
                message    = 'Use the ATM',
                onInteract = function()
                    TriggerEvent('myserver-banking:atmUse')
                end,
            },
            {
                bind      = 'G',
                message   = 'Rob the ATM',
                hintColor = 'red',
                condition = function()
                    return exports['myserver-police']:hasEnoughCops(2)
                end,
                onInteract = function(entity)
                    TriggerServerEvent('myserver-robbery:startATM', NetworkGetNetworkIdFromEntity(entity))
                end,
            },
        },
    })
end

exports.avenida_interact:pedRegister({
    coords           = vec4(-1393.81, -1064.09, 3.17, 266.09),
    model            = 'a_f_y_vinewood_04',
    animDict         = 'anim@amb@waving@male',
    animName         = 'ground_wave',
    randomComponents = false,
    message          = 'Talk with Maria',
    showIcon         = 10.0,
    canInteract      = 3.0,
    hintIcon         = 'talk',
    hintColor        = 'gold',
    blips = { sprite = 119, color = 50, text = 'Lumberjack', scale = 0.8 },
    dialogue = {
        name     = 'Maria',
        startMsg = 'Hello, are you ready to start your shift?',
        elements = {
            {
                label  = 'Yes, where do I start?',
                action = function(changeDialog, close)
                    SetNewWaypoint(-584.01, 5491.59)
                    changeDialog('The forest is on your GPS now.', {
                        { label = 'Got it!', action = function(_, close) close() end },
                    })
                end,
            },
            {
                label  = 'I\'ll come back later',
                action = function(_, close) close() end,
            },
        },
    },
})

• Brauche ich wirklich kein ox_lib?
  Nein. Seit 1.1.0 baut `bridges/compat.lua` die DUI-Erstellung, die Proximity-Points und die Wait-Helper mit reinen Natives nach, und die Zeile `@ox_lib/init.lua` ist im Manifest auskommentiert. Wenn du das lieber über ox_lib laufen lässt, setz `Config.UseOxLib = true` und kommentier die Zeile ein. Beide Wege werden gepflegt, der native ist der Standard.
• Mein Marker taucht nicht auf, wo muss ich suchen?
• Meine Auswahl-Bedingung wird ignoriert
• Welche Farben kann ich benutzen?
• Der Prompt war auf meinem Ultrawide verzerrt
• Meine Punkte bleiben sichtbar, wenn meine Resource stoppt
• Wie hänge ich es an ESX, QBCore, Qbox, ox oder vRP?
• Wie viele Punkte kann ich registrieren?