Bridge personalizzati

Gli script RZ includono file leggibili per adattare core, inventario e notifiche senza modificare gameplay o menu protetti. I file contengono chiamate VORP funzionanti. Con VORP standard, lasciali come forniti. Un altro framework richiede un developer che sostituisca le chiamate con le sue API effettive.

Quale file modificare?

File	Utilizzo
public/bridge_server.lua	Personaggio pronto, nomi, inventario ed evento di selezione del personaggio
public/bridge_client.lua	Notifiche a schermo
public/eateffects.lua in Herbs	Effetti aggiuntivi quando si mangia una pianta

Questi file rimangono leggibili con Cfx escrow. Il codice interno di gameplay, sincronizzazione, permessi, menu e notifiche native rimane protetto. Non modificare .rz: viene generata dalla build.

Come cambiare un'integrazione

1. Trova la funzione nel file pubblico: il commento ne indica argomenti e risultato.
2. Leggi l'implementazione VORP attiva come riferimento.
3. Sostituisci il corpo, mantenendo nome e argomenti. Non aggiungere una seconda chiamata dopo quella VORP.
4. Restituisci il risultato richiesto. Se l'API esterna usa callback, il risultato deve essere disponibile prima del ritorno: un return dentro una callback successiva non basta.
5. Riavvia il prodotto e prova l'operazione.

Non esiste un ripiego VORP nascosto. Una funzione mancante, vuota o con risultato errato non richiama una seconda implementazione. Una funzione inventario vuota non aggiunge item e non indica successo.

Per un inventario personalizzato adatta insieme Catalog, CanCarry e AddItem. Per un core personalizzato adatta IsReady, Profile ed evento di caricamento personaggio. Puoi usare core VORP e inventario custom o viceversa.

Ogni risorsa possiede i suoi file pubblici. Mantieni coerente l'integrazione core/inventario nei prodotti installati: il menu condiviso può essere ospitato da una diversa risorsa RZ, e il suo Catalog alimenta il selettore degli item. Notifiche e ricompense usano il bridge del prodotto che le invia.

Conserva una copia dei file pubblici prima degli aggiornamenti. Le build SDK conservano i file esistenti, anche quelli obsoleti: confronta le nuove implementazioni quando aggiorni un vecchio template e conserva le tue personalizzazioni.

Operazioni server

source è l'ID server di un giocatore connesso, non ID personaggio, licenza o PlayerId() client.

API prodotto	Funzione pubblica	Implementazione fornita
RZ.Player.IsReady(source)	RZ.Bridge.Player.IsReady(source)	Esistenza del personaggio VORP Core.getUser(source).getUsedCharacter
RZ.Player.Profile(source)	RZ.Bridge.Player.Profile(source)	firstname / lastname del personaggio
RZ.Inventory.Catalog()	RZ.Bridge.Inventory.Catalog()	Inventario avviato e query oxmysql su items, colonne item, label
RZ.Inventory.CanCarry(source,item,count)	RZ.Bridge.Inventory.CanCarry(source,item,count)	exports.vorp_inventory:canCarryItem(source,item,count)
RZ.Inventory.AddItem(source,item,count)	RZ.Bridge.Inventory.AddItem(source,item,count)	exports.vorp_inventory:addItem(source,item,count)
RZ.Notify.Left(source,payload)	Solo client: RZ.Bridge.Notify.Left(payload)	Evento al client e notifica nativa SDK

Personaggio pronto

Il bridge restituisce true quando il personaggio è caricato, false se non lo è oppure nil, "CUSTOM_ERROR" in caso di errore.

La chiamata prodotto è local ok, ready, code = RZ.Player.IsReady(source): ok indica se il controllo è riuscito; ready se il personaggio è pronto.

Profilo

Il bridge restituisce { first_name = "Jane", last_name = "Smith" }. Entrambi i nomi sono stringhe non vuote di massimo 96 byte. In caso di errore: nil, "CUSTOM_ERROR".

Chiamata prodotto: local profile, code = RZ.Player.Profile(source).

Questo bridge non espone ancora lavori, gradi, saldi, identificatori del personaggio o tutti i suoi dati.

Catalogo item

Restituisci un array consecutivo:

{
    { item = "water", label = "Water" },
    { item = "bread", label = "Bread" },
}

Massimo 4096 elementi. Gli identificatori sono unici, da 1 a 96 byte; le label da 1 a 256 byte. I campi extra vengono ignorati. {} indica catalogo vuoto; nil, "CUSTOM_ERROR" indica errore.

Il menu usa local items, code = RZ.Inventory.Catalog() per i selettori item e ricompense. Normalizza i dati del tuo inventario in questa struttura.

Capacità e aggiunta

item: stringa da 1 a 96 byte. count: intero da 1 a 100000.

• CanCarry restituisce true se la quantità entra, false altrimenti. Non deve aggiungere item.
• AddItem restituisce true solo dopo l'aggiunta riuscita, false se rifiutata.
• Usa false, "CUSTOM_ERROR" per errori di integrazione.

Le API prodotto restituiscono boolean, code: anche false, "OK" è possibile per un normale risultato negativo. Controlla sempre il booleano.

AddItem non chiama automaticamente CanCarry. Rimozione item, conteggi, metadata e contenitori custom non sono esposti da questo bridge.

Dati notifica

Campo	Contratto
title	Stringa non vuota, massimo 128 byte
message	Stringa non vuota, massimo 512 byte
dictionary, icon	Stringhe non vuote, massimo 96 byte
duration_ms	Intero 1–60000, millisecondi
color	Opzionale

La personalizzazione è solo client. La funzione fornita chiama RZ.NativeNotify.Left(payload) senza esporne l'implementazione. Sostituisci quella chiamata con il tuo sistema. Una notifica custom non richiede un valore di ritorno; gli errori non attivano una seconda notifica.

Chiamata server: local sent, code = RZ.Notify.Left(source, payload).

Herbs: personalizzare la notifica

Per cambiare solo i testi di raccolta e consumo, modifica public/notifications.lua: guida ai testi. Il bridge sotto serve a sostituire il sistema che mostra la notifica.

Modifica solo public/bridge_client.lua, funzione RZ.Bridge.Notify.Left. Herbs la usa sia per raccolta sia per consumo. Non c'è un secondo bridge notifiche server da configurare.

RZ.Bridge.Notify.Left = function(payload)
    return RZ.NativeNotify.Left(payload)
end

RZ.NativeNotify.Left mostra direttamente la notifica originale senza richiamare il bridge. Sostituisci la riga return con la chiamata al tuo sistema: non lasciare entrambe attive.

payload è una tabella Lua con la notifica già composta. Non devi calcolare ricompense o costruire il messaggio.

Valore	Contenuto
payload.title	Titolo tradotto, ad esempio Herbs
payload.message	Messaggio completo con quantità e nomi degli item assegnati
payload.duration_ms	8000 per ricompense assegnate, 5000 per consumo o nessuna ricompensa
payload.dictionary	Dizionario texture RedM della pianta
payload.icon	Nome texture della pianta
payload.color	Herbs invia COLOR_WHITE

Esempi di messaggi preparati

• Un item: raccolto x1 Yarrow.
• Più item: raccolti x1 Yarrow, x2 Water, in un'unica notifica.
• Nessun item aggiunto: messaggio di nessuna ricompensa o inventario pieno.
• Consumo: hai mangiato Yarrow, anche con effetti aggiuntivi disattivati.

Per le ricompense viene usata la label salvata, oppure l'identificatore item se non presente. Non viene interrogato l'inventario per ogni notifica. Sono mostrati solo gli item aggiunti con successo; righe separate restano separate anche per lo stesso item.

Per il consumo si usa il nome della pianta configurato. La lingua è quella dello script, non del pannello owner. L'immagine resta quella della pianta anche con ricompense diverse.

Collegare un altro sistema

Passa payload.title, payload.message e gli altri valori alla chiamata documentata dal tuo sistema. Se richiede secondi, converti payload.duration_ms / 1000. Non richiamare RZ.Notify.Left dal suo stesso bridge: creeresti una ricorsione.

Con il corpo vuoto non viene mostrata alcuna notifica: per ripristinare quella originale, reinserisci return RZ.NativeNotify.Left(payload).

Ciclo di vita del personaggio

Il prodotto si registra con RZ.Player.OnReady(function(source) ... end). Il file pubblico server contiene l'evento VORP attivo:

AddEventHandler("vorp:SelectedCharacter", function(playerSource)
    RZ.Bridge.PlayerReady(playerSource)
end)

Per un altro core sostituiscilo con il suo evento server affidabile e passa l'ID server reale a RZ.Bridge.PlayerReady. Non aggiungere un evento richiamabile dal client che accetti l'ID arbitrario di un giocatore. L'SDK non registra un secondo evento VORP nascosto. Adatta anche IsReady, che controlla chi è già connesso al riavvio della risorsa.

L'avvio della risorsa e la scelta del personaggio sono momenti diversi. Prova ingresso, riavvio a giocatore connesso, relog e cambio personaggio. La disponibilità del menu non dimostra da sola che il personaggio sia pronto per il gameplay.

Cache del catalogo

Il file pubblico server include questa funzione locale:

local function RefreshItemCatalog()
    TriggerEvent("rz:sdk:v1:inventory_changed")
end

L'evento SDK solo server invalida la cache di nomi e label del menu. Non modifica l'inventario di un giocatore e non esegue subito una query: la prossima richiesta chiama nuovamente Inventory.Catalog. Mantieni invariato il nome dell'evento SDK.

Gli handler pubblici di avvio/arresto la chiamano quando riparte vorp_inventory. Con un altro inventario cambia quel nome in entrambi gli handler. Se l'inventario permette di ricaricare gli item senza riavviarsi, collega RefreshItemCatalog() anche al suo evento server di ricarica documentato. Non aggiungere query a ogni raccolta o notifica.

Tipi di notifica client

Il template contiene 17 funzioni pubbliche, che chiamano esplicitamente RZ.NativeNotify.Method(payload). I prodotti possono includere solo quelle usate: Herbs include Left. Nessuna di queste notifiche native richiede un export VORP.

Metodo	Campi payload
Left	title, message, dictionary, icon, duration_ms, color
Tip	message, duration_ms
RightTip	message, duration_ms
Objective	message, duration_ms
Top	message, location, duration_ms
SimpleTop	title, message, duration_ms
Advanced	message, dictionary, icon, color, duration_ms, quality, show_quality
Center	message, duration_ms, color
BottomRight	message, duration_ms
Fail	title, message, duration_ms
Dead	title, audio_ref, audio_name, duration_ms
Update	title, message, duration_ms
Warning	title, message, audio_ref, audio_name, duration_ms, color
LeftRank	title, message, dictionary, icon, duration_ms, color
ThreeSimpleTop	title, message, secondary_message, duration_ms
OneSimpleTop	title, duration_ms
LeftInteractive	title, message, secondary_message, dictionary, icon, audio_ref, audio_name, duration_ms, color

I campi sono richiesti salvo color, quality e show_quality, predefiniti a "COLOR_WHITE", 1, false. Durata intera 1–60000 ms; quality intero signed 32 bit; show_quality booleano. Stringhe non vuote: titolo e location massimo 128 byte, messaggi 512, altre stringhe 96. I campi sconosciuti non passano al renderer nativo.

Una funzione custom definita viene usata anche se vuota. Può restituire false, "CUSTOM_ERROR" per segnalare un errore, senza ripiego al renderer originale. Successo indica invio, non conferma visiva.

Le texture hanno un timeout di 2 secondi. I tipi persistenti vengono rimossi allo scadere e all'arresto della risorsa. Non è implementato il riconoscimento automatico di risorse notifiche esterne.

Esempio: VORP con una chiamata diversa

Modifica la funzione interessata conservando le altre implementazioni del file:

RZ.Bridge.Inventory.AddItem = function(source, item, count)
    if not exports.vorp_inventory:canCarryItem(source, item, count) then
        return false, "INVENTORY_FULL"
    end
    return exports.vorp_inventory:addItem(source, item, count)
end

Questo non rende atomici controllo capacità e aggiunta: il gameplay deve controllare anche il risultato dell'aggiunta. Per un altro inventario traduci argomenti, identificatori, campi e risultati secondo la sua documentazione. Non chiamare RZ.Inventory.AddItem nel proprio override.

Risoluzione problemi

Errore	Significato
RZF-E-PLAYER	ID server non valido o giocatore disconnesso
RZF-E-INVENTORY-INPUT	Item o quantità non validi
RZF-E-NOTIFICATION-INPUT	Payload non valido
RZF-E-ADAPTER-RESULT	Risultato profilo/readiness non valido o errore della notifica client
RZF-E-INVENTORY-CATALOG	Struttura o limiti del catalogo non validi
RZF-E-ADAPTER-FAILURE	Errore nell'integrazione: controlla report e console
RZF-E-NOT-READY	Bridge server non inizializzato
RZF-E-BRIDGE-FUNCTION	Funzione richiesta non disponibile
RZR-E-UPDATE-REQUIRED	Aggiornamento obbligatorio noto che blocca le chiamate

Le dipendenze VORP vengono cercate al momento della chiamata. Un'integrazione mancante può far fallire un'operazione senza disabilitare tutto il menu. Lo stato pronto del bridge non dimostra che ogni funzione esterna sia corretta.

Riavvia il prodotto dopo la modifica e prova le operazioni sui sistemi effettivamente installati. Questa guida descrive il contratto SDK, non certifica compatibilità con ogni framework.