İlk BS19 kaynağın

Bu rehber sıfırdan küçük bir kaynak oluşturur: bir hayatta kalana en fazla saatte bir kez bir su şişesi veren /checkin komutu. Yaklaşık 15 dakika sürer. Çalışan bir BS19 sunucusuna, dosyalarına ve txAdmin konsoluna erişime ve bir metin editörüne (VS Code iyi iş görür) ihtiyacın var.

Çalıştığında, bs_core üzerine bir kaynak yazma sonraki adımları gösterir: istemci kodu, callback’ler ve kaçınman gereken tuzaklar.

1. Klasörü oluştur

Sunucunun resources klasöründe [local] adında bir klasör oluştur (köşeli parantezler önemli, onu bir kaynak değil kategori yapar) ve içine bs_checkin adında bir klasör aç. Kendi kaynaklarını [local] içinde tut, böylece framework güncellemeleri onları asla ezmez.

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

Klasör adı kaynak adıdır. Başka bir scriptle çakışmaması için bs_ ile başlat.

2. fxmanifest.lua

Her FiveM kaynağının bu dosyaya ihtiyacı vardır. Sunucuya hangi dosyaları hangi tarafta yükleyeceğini söyler.

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' }

@bs_core/shared/sh_bridge.lua satırı BS19 köprüsünü kaynağına yükler. O olmadan BSB yoktur ve sunucu dosyası hata verir.

3. config.lua

Bir sunucu sahibinin değiştirmek isteyebileceği her değeri tek bir tabloya koy, böylece kimse kodunu düzenlemek zorunda kalmaz.

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)

Satır satır ne yaptığı:

• BSB.RegisterCommand sohbet komutunu oluşturur. nil herkesin kullanabileceği anlamına gelir; yetkililerle sınırlamak için oraya 'bs.admin' gibi bir ACE yaz.
• GetPlayerSummary, oyuncu hâlâ karakter ekranındayken nil döner, bu yüzden önce bunu kontrol et.
• Bekleme süresi oyuncu başına değil karakter başına (charId) tutulur, yani ikinci bir karakterin kendi check-in hakkı olur. Kaynak yeniden başlatıldığında sıfırlanır; ilk kaynak için bu yeterli.
• Eşyalar her zaman exports.bs_inventory:GiveItem üzerinden verilir. Envanter doluysa false ve bir sebep döner. Veritabanına asla kendin yazma.

5. Başlat

Bu satırı server.cfg dosyasının sonuna, BS19 kaynaklarından sonra ekle:

ensure bs_checkin

Sonra txAdmin canlı konsolunda (sunucuyu yeniden başlatmaya gerek yok):

refresh
ensure bs_checkin

refresh sunucunun yeni klasörü görmesini sağlar. Konsolda Started resource bs_checkin yazmalı. Daha sonra bir dosyayı düzenlediğinde, yeniden yüklemek için yalnızca ensure bs_checkin yeterli.

6. Oyunda test et

1. Sunucuya gir ve bir karakter seç.
2. T’ye bas, /checkin yaz ve Enter’a bas. Yeşil bir bildirim alırsın ve envanterine (I) bir su şişesi gelir.
3. Tekrar /checkin yaz. Kırmızı bir “Come back in 60 min.” mesajı alırsın.

Çalışmazsa

Gördüğün	Neden	Çözüm
Couldn't find resource bs_checkin	Sunucu klasörü görmedi ya da isim farklı	refresh çalıştır, klasörün adının tam olarak bs_checkin olduğunu kontrol et
attempt to index a nil value (global 'BSB')	Köprü satırı eksik	fxmanifest.lua içindeki @bs_core/shared/sh_bridge.lua satırını kontrol et
No such export GetPlayerSummary	bs_core henüz başlamadı	server.cfg içinde ensure bs_checkin satırını BS19 kaynaklarının altında tut
/checkin hiçbir şey yapmıyor, hata yok	Hâlâ karakter ekranındasın ya da komut hiç kaydedilmedi	Bir karakter seç, sonra konsolda kırmızı bir [bs_checkin] satırı ara
“No room: …”	Envanterin dolu ya da çok ağır	Bir şey bırak ve tekrar dene

Konsoldaki her kırmızı hata dosyayı ve satırı da gösterir. Düzelt, ensure bs_checkin komutunu tekrar çalıştır ve yeniden dene.

Sonrası için fikirler

• config.lua içinde item değerini bandage yap ve ensure bs_checkin çalıştır. Kod değişikliği gerekmez.
• Biraz nakit de ver: exports.bs_core:AddMoney(src, 'cash', 25, 'checkin').
• XP ver: exports.bs_core:AddXP(src, 10, 'checkin').
• Kullanabileceğin çağrılara Export ve event özeti sayfasından göz at.