La tua prima risorsa BS19

Questa guida costruisce una piccola risorsa da zero: un comando /checkin che dà a un sopravvissuto una bottiglia d’acqua, al massimo una volta l’ora. Ci vogliono circa 15 minuti. Ti servono un server BS19 avviato, l’accesso ai suoi file e alla console di txAdmin, e un editor di testo (VS Code va benissimo).

Quando funziona, Scrivere una risorsa sopra bs_core mostra i passi successivi: codice client, callback e le trappole da evitare.

1. Crea la cartella

Nella cartella resources del server, crea una cartella [local] (le parentesi quadre contano: la rendono una categoria, non una risorsa) e al suo interno una cartella bs_checkin. Tieni le tue risorse in [local], così gli aggiornamenti del framework non le sovrascrivono mai.

resources/[local]/bs_checkin/
├── fxmanifest.lua
├── config.lua
└── server.lua

Il nome della cartella è il nome della risorsa. Inizialo con bs_ così non va in conflitto con un altro script.

2. fxmanifest.lua

Ogni risorsa FiveM ha bisogno di questo file. Dice al server quali file caricare e da quale lato.

fx_version 'cerulean'
game 'gta5'
lua54 'yes'

name 'bs_checkin'
description 'My first BS19 resource'

shared_scripts {
    '@bs_core/shared/sh_bridge.lua', -- gives you BSB (commands, callbacks)
    'config.lua',
}
server_scripts { 'server.lua' }

dependencies { 'bs_core', 'bs_inventory' }

La riga @bs_core/shared/sh_bridge.lua carica il bridge di BS19 nella tua risorsa. Senza, BSB non esiste e il file server va in errore.

3. config.lua

Metti in un’unica tabella ogni valore che il proprietario di un server potrebbe voler cambiare, così nessuno deve toccare il tuo codice.

Checkin = {
    item     = 'water_bottle', -- any item name from bs_inventory's item list
    amount   = 1,
    cooldown = 3600,           -- seconds between two check-ins (1 hour)
}

4. server.lua

local lastCheckin = {} -- [charId] = os.time() of the last check-in

local function notify(src, kind, message)
    TriggerClientEvent('bs:ui:notify', src, { type = kind, message = message })
end

BSB.RegisterCommand('checkin', nil, 'Daily survivor check-in', {}, function(src)
    if src == 0 then return print('Run /checkin in game, not in the console.') end

    local p = exports.bs_core:GetPlayerSummary(src)
    if not p then return notify(src, 'error', 'Pick a character first.') end

    local now  = os.time()
    local last = lastCheckin[p.charId]
    if last and now - last < Checkin.cooldown then
        local minutes = math.ceil((Checkin.cooldown - (now - last)) / 60)
        return notify(src, 'error', ('Come back in %d min.'):format(minutes))
    end

    local ok, reason = exports.bs_inventory:GiveItem(src, Checkin.item, Checkin.amount)
    if not ok then return notify(src, 'error', 'No room: ' .. tostring(reason)) end

    lastCheckin[p.charId] = now
    notify(src, 'success', ('Welcome back, %s. Here is some water.'):format(p.firstName))
end)

Cosa fa, riga per riga:

• BSB.RegisterCommand crea il comando in chat. nil significa che tutti possono usarlo; metti una ACE come 'bs.admin' per riservarlo allo staff.
• GetPlayerSummary restituisce nil finché il giocatore è nella schermata dei personaggi, quindi controllalo per primo.
• L’attesa è salvata per personaggio (charId), non per giocatore, quindi un secondo personaggio ha il suo check-in. Si azzera al riavvio della risorsa, che per una prima risorsa va bene.
• Gli oggetti passano sempre da exports.bs_inventory:GiveItem. Restituisce false e un motivo quando l’inventario è pieno. Non scrivere mai da solo nel database.

5. Avviala

Aggiungi questa riga alla fine di server.cfg, dopo le risorse BS19:

ensure bs_checkin

Poi, nella console live di txAdmin (non serve riavviare il server):

refresh
ensure bs_checkin

refresh fa vedere al server la nuova cartella. La console dovrebbe stampare Started resource bs_checkin. Quando in seguito modifichi un file, basta ensure bs_checkin per ricaricarla.

6. Provala in gioco

1. Entra nel server e scegli un personaggio.
2. Premi T, scrivi /checkin e premi Invio. Ricevi una notifica verde e una bottiglia d’acqua nell’inventario (I).
3. Scrivi di nuovo /checkin. Ricevi un messaggio rosso “Come back in 60 min.”.

Se non funziona

Cosa vedi	Perché	Soluzione
Couldn't find resource bs_checkin	Il server non ha visto la cartella o il nome è diverso	Esegui refresh, controlla che la cartella si chiami esattamente bs_checkin
attempt to index a nil value (global 'BSB')	Manca la riga del bridge	Controlla la riga @bs_core/shared/sh_bridge.lua in fxmanifest.lua
No such export GetPlayerSummary	bs_core non è ancora avviato	Tieni ensure bs_checkin sotto le risorse BS19 in server.cfg
/checkin non fa nulla, nessun errore	Sei ancora nella schermata dei personaggi o il comando non è mai stato registrato	Scegli un personaggio, poi cerca una riga rossa [bs_checkin] nella console
“No room: …”	L’inventario è pieno o troppo pesante	Lascia qualcosa e riprova

Ogni errore rosso nella console indica anche file e riga. Correggi, esegui di nuovo ensure bs_checkin e riprova.

Idee per continuare

• Cambia item in bandage in config.lua ed esegui ensure bs_checkin. Nessuna modifica al codice.
• Dai anche un po’ di contanti: exports.bs_core:AddMoney(src, 'cash', 25, 'checkin').
• Dai XP: exports.bs_core:AddXP(src, 10, 'checkin').
• Sfoglia le chiamate disponibili in Panoramica di export ed eventi.