Votre première ressource BS19

Ce guide construit une petite ressource à partir de rien : une commande /checkin qui donne une bouteille d’eau à un survivant, au maximum une fois par heure. Comptez environ 15 minutes. Il vous faut un serveur BS19 qui tourne, l’accès à ses fichiers et à la console txAdmin, et un éditeur de texte (VS Code fait très bien l’affaire).

Une fois que ça marche, Écrire une ressource sur bs_core montre la suite : code client, callbacks et les pièges à éviter.

1. Créer le dossier

Dans le dossier resources de votre serveur, créez un dossier [local] (les crochets comptent : ils en font une catégorie, pas une ressource) et dedans un dossier bs_checkin. Gardez vos propres ressources dans [local], les mises à jour du framework ne les écraseront jamais.

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

Le nom du dossier est le nom de la ressource. Commencez-le par bs_ pour éviter tout conflit avec un autre script.

2. fxmanifest.lua

Toute ressource FiveM a besoin de ce fichier. Il indique au serveur quels fichiers charger et de quel côté.

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 ligne @bs_core/shared/sh_bridge.lua charge le pont BS19 dans votre ressource. Sans elle, BSB n’existe pas et le fichier serveur plante.

3. config.lua

Mettez toutes les valeurs qu’un propriétaire de serveur voudrait changer dans une seule table, pour que personne n’ait à toucher votre code.

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)

Ce que fait le code, ligne par ligne :

• BSB.RegisterCommand crée la commande de chat. Le nil veut dire que tout le monde peut l’utiliser ; mettez une ACE comme 'bs.admin' pour la réserver au staff.
• GetPlayerSummary renvoie nil tant que le joueur est sur l’écran des personnages, vérifiez-le donc en premier.
• Le délai est stocké par personnage (charId), pas par joueur : un second personnage a son propre check-in. Il se remet à zéro au redémarrage de la ressource, ce qui suffit pour une première ressource.
• Les objets passent toujours par exports.bs_inventory:GiveItem. Il renvoie false et une raison quand l’inventaire est plein. N’écrivez jamais vous-même dans la base de données.

5. La démarrer

Ajoutez cette ligne à la fin de server.cfg, après les ressources BS19 :

ensure bs_checkin

Puis, dans la console live de txAdmin (pas besoin de redémarrer le serveur) :

refresh
ensure bs_checkin

refresh fait découvrir le nouveau dossier au serveur. La console doit afficher Started resource bs_checkin. Quand vous modifierez un fichier plus tard, ensure bs_checkin seul suffit à le recharger.

6. La tester en jeu

1. Rejoignez le serveur et choisissez un personnage.
2. Appuyez sur T, tapez /checkin et validez. Une notification verte apparaît et une bouteille d’eau arrive dans votre inventaire (I).
3. Tapez encore /checkin. Vous obtenez un message rouge « Come back in 60 min. ».

Si ça ne marche pas

Ce que vous voyez	Pourquoi	Solution
Couldn't find resource bs_checkin	Le serveur n’a pas vu le dossier, ou le nom diffère	Lancez refresh, vérifiez que le dossier s’appelle exactement bs_checkin
attempt to index a nil value (global 'BSB')	La ligne du pont manque	Vérifiez la ligne @bs_core/shared/sh_bridge.lua dans fxmanifest.lua
No such export GetPlayerSummary	bs_core n’est pas encore démarré	Gardez ensure bs_checkin sous les ressources BS19 dans server.cfg
/checkin ne fait rien, sans erreur	Vous êtes encore sur l’écran des personnages, ou la commande n’a jamais été créée	Choisissez un personnage, puis cherchez une ligne rouge [bs_checkin] dans la console
« No room: … »	Votre inventaire est plein ou trop lourd	Lâchez quelque chose et réessayez

Toute erreur rouge dans la console indique aussi le fichier et la ligne. Corrigez, relancez ensure bs_checkin et réessayez.

Idées pour la suite

• Remplacez item par bandage dans config.lua et lancez ensure bs_checkin. Aucune modification de code.
• Donnez aussi un peu d’argent : exports.bs_core:AddMoney(src, 'cash', 25, 'checkin').
• Donnez de l’XP : exports.bs_core:AddXP(src, 10, 'checkin').
• Parcourez les appels disponibles dans Exports & événements.