Mimari

Tek kural

bs_core durumun sahibidir. Para, XP, ihtiyaçlar, konum, karakter verisi: bunları yalnızca bs_core yazar ve satırı yalnızca bs_core kaydeder. Diğer tüm kaynaklar bs_core’a export’lar üzerinden sorar. Kayıtları dürüst tutan budur: bir karakteri değişmiş olarak işaretleyen tek bir yer ve yazan tek bir yer vardır.

Katmanlar

NUI (html in each resource, shared shell in bs_ui)
   |  SendNUIMessage / fetch (NUI callbacks)
Client Lua      mirrors state, never authoritative
   |  net events + BSB callbacks
Server Lua      Player objects, validation, hooks
   |  oxmysql (behind bs_core/server/sv_database.lua)
MariaDB         migrations in bs_core/sql

İstemci sorar, sunucu karar verir, sunucu sonucu geri gönderir. İstemcinin gönderdiği her şey sunucuda yeniden denetlenir. Örneğin ihtiyaçlar bir istemci raporundan yalnızca azalabilir, açlığı geri getirmek bir tüketilebilirden gelen sunucu eylemidir.

Kaynak haritası

Her birinin ne yaptığı Resource listesi sayfasında.

Grup	Kaynaklar
Çekirdek	bs_core, bs_loading, bs_multichar, bs_esx_bridge
UI	bs_ui (HUD, bildirim, paylaşılan NUI parçaları), bs_radial, bs_menu (merkez), bs_chat, bs_scoreboard
Oyuncu	bs_inventory, bs_skills, bs_medical, bs_bodily, bs_emotes, bs_boosters, bs_gadgets, bs_drugs
Dünya	bs_world, bs_interactions (ALT target dot, containers), bs_economy (loot), bs_traders, bs_vehicles, bs_building, bs_crafting, bs_gates, bs_stash, bs_recycler, bs_mining, bs_scenes, bs_events, bs_extraction
Zombiler	bs_zombies, bs_zombiepeds, bs_zombiesfx, bs_atlas, nodes
Sosyal	bs_factions, bs_faction_bases, bs_jobs, bs_vip
Personel	bs_admin, bs_tester, bs_config, bs_guard, bs_cinecam
Varlıklar	bs_assets

Oturum durumları

connecting -> playerConnecting: identity resolved, ban checked
loading    -> client handshake (bs:session:clientReady)
select     -> limbo, frozen and invisible, character list/create/delete/select
playing    -> Player object exists server side, ped spawned

/logout ve bağlantı kopması ikisi de önce zorla kaydeden BS.UnloadPlayer’dan geçer. İstemci tarafında exports.bs_core:GetSessionState() nerede olduğunuzu söyler, exports.bs_core:IsLoaded() ise basit “karakter var mı” denetimidir.

Başka bir kaynaktan oyuncu verisi

Player nesnesi bs_core’un Lua durumunda yaşar. Fonksiyonlar export sınırını geçmez, bu yüzden nesneyi almazsınız, işi yapan export’ları çağırırsınız:

-- server
local p = exports.bs_core:GetPlayerSummary(src)   -- plain table: charId, name, level, xp, accounts, needs, role...
exports.bs_core:AddMoney(src, 'cash', 50, 'my_reason')
exports.bs_core:RemoveMoney(src, 'bank', 200, 'my_reason')
exports.bs_core:AddXP(src, 25, 'my_reason')
local v = exports.bs_core:GetPlayerMeta(src, 'my_key', nil)
exports.bs_core:SetPlayerMeta(src, 'my_key', { any = 'table' })
exports.bs_core:AwardAction(src, 'zombie_kill')   -- uses Config.Rewards

İstemci tarafı: exports.bs_core:GetData(), GetNeeds(), IsLoaded().

Karakter üst verisi (GetPlayerMeta/SetPlayerMeta) karakter başına küçük veriler için kolay yerdir. bs_drugs bağımlılığı kendi tablosu olmadan orada tutar.

Kancalar

bs_core’un süreç içi bir pub/sub’ı (BS.On / BS.Emit) vardır ve her kancayı bs:hook:<name> adlı normal bir olay olarak yeniden yayınlar. Kaynağınızdan:

AddEventHandler('bs:hook:player:loaded', function(data) ... end)
AddEventHandler('bs:hook:player:unloaded', function(...) ... end)

Kanca	Taraf
core:ready	ikisi
player:loaded, player:spawned, player:unloaded	ikisi
player:money, player:levelUp	ikisi
player:xp, player:action	server
character:created, character:selected	server
session:state, needs:changed	client

Callback köprüsü (BSB)

Net olayları üzerinden istek/yanıt. Dosyayı manifestinize ekleyin, kendi Lua durumunuzda BSB olsun:

shared_scripts { '@bs_core/shared/sh_bridge.lua' }

-- server
BSB.RegisterCallback('mything:get', function(src, a, b)
    return { ok = true, value = a + b }
end)

-- client
local res = BSB.Await('mything:get', 5000, 1, 2)   -- blocks this thread, nil on timeout

Diğer yön, sunucu tek bir istemciye sorar:

-- client
BSB.RegisterClientCallback('mything:where', function() return GetEntityCoords(PlayerPedId()) end)
-- server
local pos = BSB.AwaitClient(src, 'mything:where', 3000)

Nasıl çalışır: istek her kaynağa yayınlanır, adı kaydeden yanıtlar, diğerleri sessiz kalır. Yani:

• bilinmeyen veya durdurulmuş bir ad zaman aşımına uğrar, hata vermez
• adlar geneldir, sisteminizin önekini ekleyin (squad:invite, factions:roster, vendor:buy)
• sunucu her istemciyi kaynak başına saniyede 40 istekle sınırlar
• hata fırlatan bir işleyici callback "x" errored yazdırır ve istemci nil alır

Dönüşler için kural, ok içeren ve başarısızlıkta error bulunan bir tablodur: { ok = false, error = 'Not in a squad.' }.

Ayrıca BSB.RegisterCommand(name, ace, help, args, handler) (ACE denetimi, pcall ve sohbet önerisi tek seferde) ve radyal çark için istemcide BSB.Radial(spec) var. Kendinizinkini yazmak yerine bunları kullanın.

Hizmetler

@bs_core/shared/sh_services.lua BS.Provide / BS.Use sağlar. Export çağırmanın denetimli bir yoludur: sağlayıcı ne sunduğunu söyler, tüketici bir tanıtıcı veya yüksek sesli bir günlük satırı alır, asla sessiz bir nil değil.

local inv = BS.Use('inventory')
if inv then inv.GiveItem(src, 'bandage', 1) end

Yenidir, çoğu kod hâlâ export’ları doğrudan çağırır. İkisi de çalışır.

Kullanılan statebag’ler

Bag	Üzerinde	Ayarlayan	Anlamı
bsDowned	oyuncu	bs_medical	oyuncu yere düştü
bsDead, bsRevivable	oyuncu	bs_medical
bsDrugMods	oyuncu (yerel)	bs_drugs	drain, regen, cap, infection, sway
bsSteady	oyuncu (yerel)	bs_boosters	geri tepme/salınım çarpanı
bsDrone	oyuncu	bs_gadgets	drone uçurma
bsSquad	oyuncu	bs_factions	manga bilgisi
bsFactionStyle, bsFactionTag, bsFactionCanInvite, bsFactionSafeZone	oyuncu	bs_factions	etiket stili, izinler, güvenli bölge
bsVipTag	oyuncu	bs_vip	{ tier, colour, style, hex, blip, hud }, VIP yoksa nil
bsInRaid, bsRogue	oyuncu	bs_extraction	PvP bölgesi durumu
bsSitting	oyuncu	bs_emotes
bsZombie	varlık	bs_zombies	yürüyen kayıt kimliği. Ayrıca ağ modunda zType, zGait, zState…
bsZombieDead	varlık	bs_zombies	ağ cesedi
bsCorpse	varlık	bs_medical	oyuncu gövdesi
bsProtected, bsKeep	varlık	çok	bs_world’ün temizlik taraması onu atlar
bsVehicle, bsLocked, bsOwned, bsWindowsDown	araç	bs_vehicles
bsBuilt	varlık	bs_building

bs_world tarafından temizlenmemesi gereken bir varlık oluşturuyorsanız, üzerine bsProtected ayarlayın.

Olay adlandırma

bs:<system>:<thing>, sonda lower camel case:

bs:session:clientReady   bs:characters:select   bs:player:money
bs:inventory:state       bs:squad:sync          bs:z:add
bs:ui:notify             bs:ui:opened           bs:medical:died

bs_core kendi adlarını BS.Events içinde tutar (bs_core/shared/sh_events.lua), böylece hiçbir şey sabit yazılmaz. Kancalar bs:hook:*’dır. Callback adları bs: öneki olmadan system:action kullanır.

Kaynak başına her olay ve callback API başvurusunda.