Dostrajanie ekwipunku i wagi: Od items.lua do metadanych

TL;DR: Ten przewodnik dostarcza gotowe do produkcji ustawienia wagi\/miejsc, tabele budżetu przedmiotów, do skopiowania i wklejenia items.lua definicje (ESX\/QBCore\/ox_inventory) oraz bezpieczne scenariusze migracji między popularnymi ekwipunkami. Użyj go, aby wyeliminować dramaty związane z przeciążeniem, zatrzymać nadmiar przedmiotów i utrzymać spójność swojej ekonomii.

---

Dlaczego dostrajanie ekwipunku ma znaczenie

Stabilna ekonomia RP zależy od niedoboru, tarcia i znaczących wyborów. Zasady ekwipunku (miejsca, waga, limity stosów, metadane takie jak trwałość\/numery seryjne) są dźwigniami, które czynią te wybory realnymi. Jeśli każdy może nosić wszystko, ceny załamują się, a pętle się psują. Najpierw dostrój ekwipunek, a następnie iteruj swoje ceny, wypłaty i pochłaniacze. Aby uzyskać szersze spojrzenie na ekonomię, zobacz nasz filar: Projektowanie zrównoważonej ekonomii GTA RP: Ceny, Pochłaniacze, Postęp.

---

Modele: Miejsca vs. Waga vs. Hybryda

Tylko miejsca

• Prosty model poznawczy; każdy przedmiot = 1 miejsce lub zdefiniowany przez klasy rozmiarów.
• Słaby w rozróżnianiu ciężkich i lekkich stosów; exploity poprzez wiele małych przedmiotów o wysokiej wartości.

Tylko waga

• Każdy przedmiot ma wagę (zwykle gramy). Gracze mają maxWeight na pojemnik. Silny realizm; wymaga przemyślanych domyślnych ustawień.

Hybryda (zalecane)

• Globalny limit wagi I limit miejsc. Zapobiega exploitom zarówno mikroprzedmiotów, jak i megaprzedmiotów. Działa najlepiej dla RP.

Wskazówka: Zachowaj liczby czytelne dla człowieka. Jeśli modelujesz w gramach, używaj liczb całkowitych (np., water = 500g) i zaokrąglaj limity graczy (np., maxWeight = 120,000).

---

Domyślne ustawienia (skopiuj i dostosuj)

Poniżej znajdują się sprawdzone w boju punkty startowe. Regulacja ±10–20% po tygodniu telemetrii miejskiej.

Ekwipunek gracza (przy sobie)

Skala serwera	Model	Maks. waga (g)	Sloty	Uwagi
Nowy/Mały (≤40 pop)	Hybryda	80,000	30	Szybsze wdrażanie; mniej początkowych problemów.
Średni (40–150)	Hybryda	120,000	35	Zrównoważony dla ogólnej RP; dobry dla różnych zawodów.
Wysoka populacja (150+)	Hybryda	150,000	32	Ogranicz sloty, aby zapobiec gromadzeniu; utrzymaj uczciwą wagę.

Pojazdy (domyślne)

Pojemnik	Maks. waga (g)	Sloty	Uzasadnienie
Schowek	10,000	5	Mały schowek, zachęca do planowania.
Bagażnik sedana	80,000	20	Podstawa.
Bagażnik SUV/Van	120,000	25	Pojazdy użytkowe stają się znaczące.
Ciężarówka (użytkowa)	180,000	28	Logistyka rozgrywki.
Schowek motocykla	8,000	3	Minimalne chowanie.

Skrytki i specjalne pojemniki

Typ	Maks. waga (g)	Sloty	Uwagi
Schowek domowy (poziom 1/2/3)	120k / 180k / 240k	40 / 60 / 80	Zachęca do ulepszania domów.
Szafka na prace	80,000	20	Zapobiega exploitom przenoszenia.
Szafka na dowody	240,000	120	Wygoda dla admina/funkcjonariusza; wymagane logowanie audytu.

---

Budżety wag przedmiotów (według klasy)

Użyj tego, aby przypisać spójne wagi. Myśl o względnym tarciu a nie realizmie.

Klasa	Przykłady	Sugerowana waga (g)
Bardzo lekki	Ostrze wytrycha, USB, SIM	5–50
Lekki	Amunicja do pistoletu (10), bandaż, przekąska	100–250
Średni	Butelka wody, burger, zestaw naprawczy	400–800
Ciężki	Pudełko amunicji do karabinu (30), butla z tlenem, skrzynia materiałów	1,500–4,000
Bardzo ciężki	Skrzynia z bronią, worek z pieniędzmi (oznaczony)	6,000–12,000

Amunicja: Budżet na jednostkę dla stosów połączonych (np., 9mm = 15g każda → 30 naboi ≈ 450g) lub reprezentować jako pudła (np., 9mm box (30) = 500g).

---

Rozmiary stosów i strategia slotów

• Commodities (jedzenie, leki): stosuj 5–20, aby zmniejszyć monotonność.
• Amunicja: stos 30–60 dla pistoletów; 60–120 dla karabinów, gdy są w pudełku.
• Materiały do tworzenia: stos 100–250; zachowaj znaczącą wagę.
• Broń: stack = 1, unikalne metadane (numer seryjny, wytrzymałość).

---

Wzorce metadanych (wytrzymałość, numery seryjne, załączniki, jakość)

Design metadata like a small schema. Keep fields minimal, typed, and validated.

Kanoniczny schemat metadanych (zalecenie)

{
 "serial": "string", // weapon unique id
 "owner": "citizenid|identifier",
 "durability": 0.0, // 0.0–1.0; decay per use/time
 "quality": 100, // 0–100; repairable threshold 25
 "ammo": 0, // integer; weapon mags
 "tint": 0, // integer (game tint index)
 "attachments": ["flashlight", "scope"],
 "expiry": 0, // unix timestamp; perishable items
 "notes": "" // small text; avoid bloat
}

Wytrzymałość i rozpad

• Broń: decay 0.5–1.5% per magazine; jam chance <5% below 20% quality.
• Narzędzia (lockpicks, drill): consume % on use; break at 0.
• Produkty łatwo psujące się: expiry check at use; stale penalty or block.

Bezpieczeństwo i wydajność

• Waliduj metadane po stronie serwera; nigdy nie ufaj zapisom klienta.
• Rozmiar metadanych (np. <512 bajtów). Duże obiekty blob wpływają negatywnie na zapis/odczyt i dane sieciowe.
• Użyj wyliczeń dla dodatków i odcieni.

---

ESX (es_extended) przykład

-- esx items.lua (example) — weight in grams; negative weight means not counted in legacy modes
['water'] = { label = 'Water Bottle', weight = 500, stack = true, close = true, description = 'Stay hydrated.' },
['bandage'] = { label = 'Bandage', weight = 150, stack = true, close = true },
['lockpick'] = { label = 'Lockpick', weight = 50, stack = true, close = true },
['pistol_ammo'] = { label = 'Pistol Ammo (30)', weight = 450, stack = true, close = true, description = '9mm, box of 30.' },
['weapon_pistol'] = { label = 'Pistol', weight = 1500, stack = false, close = true, degrade = 0.01, unique = true },

Dla wariantów ESX, które nadal używają limit zamiast waga, ustaw limit = -1 (nieograniczony) i globalnie przełączaj równowagę ekonomiczną za pomocą wagi.

QBCore (shared/items.lua) przykład

-- qb-core shared/items.lua
['water'] = { name = 'water', label = 'Water Bottle', weight = 500, type = 'item', image = 'water.png', unique = false, useable = true, shouldClose = true, description = 'Stay hydrated.',
 combinable = nil },
['bandage'] = { name = 'bandage', label = 'Bandage', weight = 150, type = 'item', image = 'bandage.png', unique = false, useable = true, shouldClose = true },
['lockpick'] = { name = 'lockpick', label = 'Lockpick', weight = 50, type = 'item', image = 'lockpick.png', unique = false, useable = true, shouldClose = true },
['pistol_ammo'] = { name = 'pistol_ammo', label = 'Pistol Ammo (30)', weight = 450, type = 'item', image = 'pistol_ammo.png', unique = false, useable = true, shouldClose = true },
['weapon_pistol'] = { name = 'weapon_pistol', label = 'Pistol', weight = 1500, type = 'weapon', image = 'weapon_pistol.png', unique = true, useable = false, shouldClose = true,
 info = { serial = '', durability = 1.0, ammo = 12, attachments = {} } },

ox_inventory (data/items.lua) przykład

return {
 water = {
 label = 'Water Bottle',
 weight = 500,
 stack = true,
 client = { status = { thirst = 25000 }, anim = { dict = 'mp_player_intdrink', clip = 'loop_bottle' } },
 },
 bandage = { label = 'Bandage', weight = 150, stack = true },
 lockpick = { label = 'Lockpick', weight = 50, stack = true },
 pistol_ammo = { label = 'Pistol Ammo (30)', weight = 450, stack = true },
 weapon_pistol = {
 label = 'Pistol', weight = 1500, stack = false, allowArmed = true,
 consume = 0, -- handled by durability system
 ammo = { type = 'AMMO_PISTOL', count = 12 },
 metadata = { serial = true, durability = true, attachments = true },
 },
}

ox_inventory obsługuje bogate client/server zachowania w definicjach przedmiotów — preferuj wbudowane nad skryptami ad hoc, aby standaryzować zachowanie.

---

Konfiguracja kontenera QBCore (przykład)

-- qb-inventory/server/config.lua (illustrative)
Config.PlayerMaxWeight = 120000
Config.PlayerMaxSlots = 35
Config.Vehicle = {
 glovebox = { weight = 10000, slots = 5 },
 trunk = function(class)
 if class == 'sedan' then return 80000, 20 end
 if class == 'suv' or class == 'van' then return 120000, 25 end
 if class == 'truck' then return 180000, 28 end
 return 60000, 18
 end
}

ox_inventory konfiguracja skrytki (przykład)

-- ox_inventory/server/custom/stashes.lua
lib.addstash('house_tier1', 40, 120000)
lib.addstash('house_tier2', 60, 180000)
lib.addstash('house_tier3', 80, 240000)

---

Playbooki migracji (bezpieczne i odwracalne)

Zasady

1. Najpierw Snapshot DB. 2) Migruj przedmioty/metadane za pomocą skryptów idempotentnych. 3) Uruchom równolegle na serwerze stagingowym. 4) Zapewnij możliwość wycofania zmian SQL.

A) qb-inventory → ox_inventory

Pola mapy

• QB items.lua → ox data/items.lua (name, label, weight, stack/unique, client/server behaviors).
• player inventory tabela: konwertuj info JSON → metadata (numer seryjny, wytrzymałość, amunicja).

Pseudokod (Lua/SQL mix)

-- 1) Export QB items to a Lua table/JSON
-- 2) Generate ox items.lua entries
-- 3) Transform inventories
for item in qb_inventory_rows do
 local meta = json.decode(item.info or '{}')
 local metadata = {
 serial = meta.serial,
 durability = meta.durability or 1.0,
 ammo = meta.ammo or 0,
 attachments = meta.attachments or {},
 }
 insert_into_ox_inventory(item.name, item.amount, metadata)
end

Przykład SQL (styl PostgreSQL/MySQL)

-- Backup
CREATE TABLE backup_playeritems AS SELECT * FROM playeritems;

-- Transform example for a single item family
UPDATE playeritems
SET metadata = JSON_OBJECT(
 'serial', JSON_EXTRACT(info, '$.serial'),
 'durability', COALESCE(JSON_EXTRACT(info, '$.durability'), 1.0),
 'ammo', COALESCE(JSON_EXTRACT(info, '$.ammo'), 0),
 'attachments', COALESCE(JSON_EXTRACT(info, '$.attachments'), JSON_ARRAY())
)
WHERE name IN ('weapon_pistol','weapon_pistol_mk2');

Pułapki

• Unikalne przedmioty: wymuś stack = false; upewnij się, że duplikaty się nie łączą.
• Systemy amunicji: uzgodnij konwencje dotyczące amunicji w pudełkach i luzem.
• Obrazy/ikony: zmień ścieżki obrazów przedmiotów, aby pasowały do nazewnictwa ox.

B) ESX (oparty na limitach) → model wagi

1. Ustaw globalne useWeight = true w konfiguracji (różni się w zależności od forka).
2. Zamień na element limit z weight (g). Dla przedmiotów wcześniej limit = -1, przypisz realistyczne wagi.
3. Przenieś odpowiednio limity schowków/pojazdów.

Skryptowane podanie

for name, item in pairs(Items) do
 if item.limit and not item.weight then
 item.weight = estimateWeightFromClass(name)
 item.limit = nil
 end
end

C) qs-inventory / lj-inventory → QBCore/ox

• Mapowanie pól jest podobne do QB: info → metadata.
• Uważaj na niestandardowe klawisze (quality, image, createdAt). Znormalizuj do kanonicznego schematu.

---

Workflow balansowania (sprint 1‑tygodniowy)

1. Dzień 0: Zaimplementuj presety; migruj przedmioty do tabeli budżetowej.
2. Dzień 1-2: Przechwytuj dane telemetryczne: średnia waga przenoszenia, używane sloty, dystrybucja przedmiotów według pracy.
3. Dzień 3: Tighten outliers (+5–10% weight on top 5 hoarded items).
4. Dzień 4-5: Role pojazdów: wzmocnienie schowków użytkowych; osłabienie nadużywania schowków.
5. Dzień 6: Produkty łatwo psujące się: dodaj expiry dla wysoko marżowych materiałów eksploatacyjnych.
6. Dzień 7: Opublikuj notatki o poprawkach; ustal dwutygodniowy przegląd.

Minimalna telemetria

• % time encumbered, avg slots used, 20 najlepszych przedmiotów pod względem liczby i całkowitej wagi, percentyle wykorzystania schowka.

---

Lista kontrolna QA (gotowa do wydania)

• Wszystkie przedmioty mają weight, stack, i jasne etykiety.
• Broń to unique/non‑stack i uwzględnij serial, durability.
• Kontenery wymuszają obydwoma waga i sloty (tam, gdzie jest to obsługiwane).
• Klasy pojazdów odpowiadają rozsądnym pojemnościom.
• Skrytki podzielone na poziomy z postępem.
• Migracje zrobione kopie zapasowe; testowano przywracanie.
• Rozmiar metadanych ograniczony; walidowany po stronie serwera.

---

Budżet wagowy CSV (skopiuj do Arkuszy Google)

name,label,class,weight_g,stack,stack_size
water,Water Bottle,consumable,500,true,10
bandage,Bandage,medical,150,true,5
lockpick,Lockpick,tool,50,true,10
pistol_ammo,Pistol Ammo (30),ammo,450,true,5
weapon_pistol,Pistol,weapon,1500,false,1

Tabela pojemności pojazdów (CSV)

container,weight_g,slots
Glovebox,10000,5
Sedan Trunk,80000,20
SUV/Van Trunk,120000,25
Truck Trunk,180000,28
Motorcycle,8000,3

---

Częste pułapki i poprawki

• Gracze zawsze obciążeni → Reduce top‑3 ubiquitous item weights by 15%; increase player cap by 10%.
• Niekończące się gromadzenie mikroprzedmiotów → Wprowadź limit slotów; ustaw minimalną wagę przedmiotu (np. 25g).
• Inflacja gospodarcza poprzez gromadzenie zapasów → Dodaj produkty łatwo psujące się expiry, tarcie wejściowe wagi wytwarzania lub opłaty za schowek.
• Przepełnienie bazy danych → Przytnij klucze metadanych; unikaj dużych notes pola.

---

Następne kroki

• Wdróż powyższe presety hybrydowe, a następnie iteruj z telemetrią.
• Dopasuj tarcie ekwipunku do wypłat i cen – zobacz nasza gospodarka po dla zlewozmywaków i modeli progresji, które dobrze pasują do tych ustawień.

Masz pytania dotyczące konkretnego forka frameworka lub niestandardowego ekwipunku? Podaj szczegóły, a dostosuję dokładne konfiguracje.