U produkciji, delovi u testiranju
Spasavanje legacy koda na živom serveru
Prepravljanje nasleđenih sistema na serveru koji nikad ne staje: telefoni i radio-stanice napisani iz početka, podaci svakog plugina prebačeni na MySQL, oprema koja ne može da izgubi predmete i migracija gepeka koja seli skladište svakog igrača a da se ništa ne izgubi.
- Uloga
- Dizajn i implementacija, samostalno
- Stack
- Lua (GLua), NutScript, MySQL, Python za alate
- Kontekst
- Diverge Networks, roleplay server koji radi godinama
- Status
- Telefoni i sloj podataka uživo; oprema, gepeci i brzina u testiranju
Snimci ekrana i klipovi na ovoj stranici napravljeni su na razvojnom serveru, sa test-karakterima i pripremljenim podacima.
Pristup
Veći deo servera koji radi godinama čini kod koji je napisao neko drugi, kod koji nikad nije završen ili kod pisan za server koji se u međuvremenu promenio. To volim. Nekad je posao da se nađe ta jedna čista ispravka, a da se ne probude sva ostala čudovišta. Nekad je posao da se lavirint od živice pretvori u moderan stan.
U oba slučaja igrači moraju moći da igraju dok se to dešava, i ništa što je njihovo ne sme usput da nestane.
Telefoni i radio-stanice, napravljeni iz početka
U produkciji od 2025.
Stari sistem telefona i radija bio je toliko nepouzdan da je server tražio da se potpuno prepiše: pozivi koji se nikad nisu završavali, igrači zaglavljeni u pozivima koji više nisu postojali i policijski kanali koje je mogao da prisluškuje bilo ko.
- Brojevi se dodeljuju pri prvom korišćenju, uz proveru da li je broj već zauzet, a podržavaoci servera mogu da izaberu sopstveni broj.
- Pozivi prolaze kroz eksplicitna stanja, a neodgovoreni pozivi se sami zatvaraju posle 30 sekundi.
- Kada igrač napusti poziv sa govornice, čišćenje se izvršava u zaštićenom bloku, tako da se poziv prekida i njegovo mrežno stanje briše čak i ako nešto pukne na pola puta.
- Periodična provera pronalazi igrače označene kao da su u pozivu koji više ne postoji i oslobađa ih.
- Radio-kanali sa enkripcijom i novi govorni balončić. Frekvencije 911 su samo za policiju, a jedan način da se ta provera zaobiđe je zatvoren.
- Puna podrška za jezike u igri i na telefonima i na radiju.
Snimak ekrana uskoro
Interfejs telefona dok se bira broj.
assets/projects/phone-radio/phone-dial.webp (uzak isečak)
Video uskoro
Jedan poziv od biranja broja, preko javljanja, do spuštanja slušalice; javlja se drugi klijent.
assets/projects/phone-radio/phone-call.mp4 (oko 15 sekundi)
Snimak ekrana uskoro
Govorni balončić radija dok neko priča.
assets/projects/phone-radio/radio-bubble.webp (uzak isečak)
Podaci svakog plugina prebačeni na MySQL
U produkciji od 2025.
Pluginovi su svoje podatke čuvali u fajlovima na serveru. Prvo sam na MySQL prebacio vrata, pa onda sve pluginove, uz komandu za upload koja je prenela stare podatke iz fajlova.
Novi sloj podataka garantuje da se čitanja i upisi svakog plugina izvršavaju redosledom kojim su zadati:
- Svaki plugin dobija svoj red, a njegove operacije nad bazom izvršavaju se strogo jedna po jedna. Čitanje nikad ne može da pretekne upis koji je došao pre njega.
- Svaki poziv vraća promise koji se razrešava kada se završi baš ta operacija.
- Red nastavlja dalje i posle uspeha i posle greške, tako da jedan loš upit nikad ne može da zaglavi plugin.
- Vrednosti se keširaju, pa čitanja idu u bazu samo kada se eksplicitno traži osvežavanje.
- Sačuvani podaci se dekodiraju unutar zaštićenog poziva, tako da se oštećeni podaci čisto odbacuju umesto da obore onoga ko ih je tražio.
-- Every plugin gets its own queue. Operations run strictly one at a time,
-- so a read can never overtake the write before it.
function PLUGIN:QueuePreparedCall(...)
local d = deferred.new()
self.__MySQL_queue = self.__MySQL_queue or {}
table.insert(self.__MySQL_queue, { deferred = d, args = {...} })
self:__MySQL_execute_next_in_queue()
return d -- settles when this particular operation is done
end
function PLUGIN:__MySQL_execute_next_in_queue()
if (not MYSQLOO_PREPARED or not MYSQLOO_PLUGIN_DATA_READY) then return end -- kicked again once the database is ready
if (self.__MySQL_CurrentOperation) then return end -- one at a time
if (not self.__MySQL_queue or table.IsEmpty(self.__MySQL_queue)) then return end
local op = table.remove(self.__MySQL_queue, 1)
self.__MySQL_CurrentOperation = op
-- unpack stops at the first nil, so find the real argument count:
-- a nil in the middle of the arguments becomes SQL NULL instead of cutting the call short.
local n = 1
for k in pairs(op.args) do n = math.max(n, k) end
-- Advance on success and on failure alike, so one bad query can never stall the plugin.
nut.db.preparedCallDeferred(unpack(op.args, 1, n)):next(function(...)
op.deferred:resolve(...)
self.__MySQL_CurrentOperation = nil
self:__MySQL_execute_next_in_queue()
end):catch(function(...)
op.deferred:reject(...)
self.__MySQL_CurrentOperation = nil
self:__MySQL_execute_next_in_queue()
end)
end
function PLUGIN:getDataMySQL(default, global, ignoreMap, refresh)
-- ... cached values are returned without touching the database (omitted)
return self:QueuePreparedCall("pluginDataGet", key):next(function(response)
local data = response and response.results and response.results[1] and response.results[1].data
if (not data) then return default end
-- Corrupt data is rejected cleanly instead of crashing the caller.
local ok, decoded = pcall(pon.decode, data)
if (not ok) then return deferred.reject(decoded) end
return decoded[1]
end)
endOprema koja ne može da se izgubi
Napravljeno, u testiranju
Kada se obuče odeća, predmet se iz mreže inventara prebacuje u skriveno stanje. Nasleđeni kod za opremanje nije imao bezbedan put nazad ako nešto krene po zlu na pola puta, pa su predmeti nestajali.
Opremanje i skidanje opreme napisao sam iznova kao jedan API zasnovan na promise-ima koji koriste svi tipovi predmeta, sa zaštitom na svakom koraku, i dodao proveru pri učitavanju karaktera koja pronalazi predmete zaglavljene u tom skrivenom stanju, vraća ih na mesto i kaže igraču šta se desilo.
-- One equip API for every item type. Each step returns a promise, so callers
-- only react once the item has really moved.
local ITEM = nut.meta.item
function ITEM:equip()
local d = deferred.resolve()
if (self.usesEquipSlot) then
d = self:addToVoid() -- out of the inventory grid, into the hidden equipped state
end
return d:next(function()
local special = special_cases[self.base] -- weapons, medals and outfits handle their own visuals
if (special) then return special(self) end
self:setData("equip", true)
self:transmitEquipState()
end)
end
function ITEM:unEquip()
local d = deferred.resolve()
if (self:isInVoid()) then
d = self:removeFromVoid()
end
return d:next(function()
if (self:isEquipped()) then
self:setData("equip")
self:transmitEquipState() -- ... owner lookup omitted
end
end)
end
function ITEM:isInVoid()
return self:getData("x", -1) == -1 or self:getData("y", -1) == -1
end
-- The way back. Every failure is a rejection with a reason, never a lost item.
function ITEM:removeFromVoid()
if (not self:isInVoid()) then return deferred.resolve() end
local inv = nut.inventory.instances[self.invID]
local charID = istable(inv) and tonumber(inv:getData("char"))
if (not (charID and nut.char.loaded[charID])) then return deferred.reject("charNotFound") end
if (not inv) then return deferred.reject("invNotFound") end
if (not inv:findFreePosition(self.uniqueID)) then return deferred.reject("noFit") end
return inv:add(self)
end
-- On character load: anything sitting in the hidden state without being
-- equipped is stuck there. Put it back and tell the player what happened.
for _, item in pairs(char:getInv():getItems()) do
if (not item:isEquipped() and item:isInVoid()) then
item:unEquip():next(function()
ply:notify("Your " .. item:getName() .. " was stuck in the void of despair. It has been moved back to your inventory, hopefully, if you had space. If not clear some, then reload your character.")
end):catch(function(err)
ply:notify("Your " .. item:getName() .. " was stuck in the void of despair. We tried to move it back into your inventory but got the following error: " .. tostring(err) .. ". Try fixing it, then reloading your char. Or contact staff!")
end)
end
endSvi gepeci u jedan, bez ijednog izgubljenog predmeta
Napravljeno, u testiranju
Ranije je svako vozilo imalo sopstveni gepek. Zamenjuje ih jedan zajednički gepek po karakteru, a migracija se pokreće automatski kada se svaki karakter prvi put učita posle update-a.
- Predmeti se prebacuju jedan po jedan, redom, tako da nikad ne dođe do race condition-a između dva prenosa.
- Ako je zajednički gepek pun, predmet umesto greške završava u inventaru izgubljenih stvari kod prodavca automobila.
- Ako prebacivanje ne uspe, predmet se vraća na svoje prvobitno mesto. Ako ni to ne uspe, server prijavljuje grešku u kojoj navodi o kom predmetu je reč.
- Zapis svakog vozila u bazi čuva ID inventara koji mu služi kao gepek (njegov invID). On se prebacuje na zajednički gepek tek kada se svi predmeti premeste, pa greška na pola puta ostavlja stari gepek kao izvor istine.
- Svaki korak se upisuje u log migracije sa datumom.
Da bi greške putovale nazad uz lanac, morao sam da zaobiđem bug u biblioteci za promise-e koju server koristi. Više o tome u nastavku.
Video uskoro
Učitava se test-karakter čiji su predmeti razbacani po gepecima nekoliko vozila. Zajednički gepek se otvara sa svime na jednom mestu, a zatim izgubljene stvari kod prodavca automobila pokazuju višak.
assets/projects/legacy-rescue/trunk-migration.mp4 (20 do 30 sekundi)
Snimak ekrana uskoro
Inventar zajedničkog gepeka, 10 sa 10, delimično popunjen.
assets/projects/legacy-rescue/shared-trunk.png (uzak isečak samo panela)
-- Move one item between inventories. If the move fails, put it back where it
-- was; if even that fails, raise an error naming the item.
function PLUGIN:AttemptServerItemTransfer(item, target, forceAdd)
local itemID = item:getID()
local source = nut.inventory.instances[item.invID]
if (not source or not source.items[itemID]) then
return rejectAsync("Item's current inventory does not exist.")
end
local oldX, oldY = item:getData("x"), item:getData("y")
local function revert(reason)
return source:add(item, oldX, oldY):next(function()
return rejectAsync(reason) -- back in place; report the original failure
end, function(revertErr)
ErrorNoHalt("[Transfer] REVERT FAILED for item " .. itemID .. ": " .. tostring(revertErr)
.. " (original: " .. tostring(reason) .. ") - item is in no inventory!\n")
return rejectAsync("revertFailed")
end)
end
return source:removeItem(itemID, true):next(function()
if (forceAdd) then
target:addItem(item) -- overflow: no grid limits
return
end
return target:add(item):next(function(res)
if (istable(res) and res.error) then return revert(res.error) end
end, revert)
end)
end
function PLUGIN:MigrateTrunkToSharedInv(char, vehicle, sharedInv, overflowInv)
-- ... guards against migrating a trunk into itself omitted
return nut.inventory.loadByID(vehicle._invID):next(function(oldTrunk)
-- Chain the moves so items go one at a time and never race each other.
local chain = deferred.resolve()
for _, item in pairs(oldTrunk:getItems()) do
chain = chain:next(function()
return self:AttemptServerItemTransfer(item, sharedInv):catch(function()
-- Shared trunk full: fall back to the lost-and-found inventory.
return self:AttemptServerItemTransfer(item, overflowInv, true)
end)
end)
end
return chain
end):next(function()
-- Only reached if every item moved. Until now the old trunk is still
-- the source of truth, so a failure halfway loses nothing.
return nut.db.preparedCallDeferred("vehicleUpdateInvID", sharedInv:getID(), vehicle.id):next(function()
vehicle._invID = sharedInv:getID()
return { vehicle, sharedInv }
end)
end)
-- ... every step is also written to a dated migration log (omitted)
endKompromis
Uklanjanje predmeta i njegovo dodavanje negde drugde nisu jedna transakcija u bazi, pa bi pad servera između ta dva koraka i dalje mogao da izgubi taj jedan predmet. Put za vraćanje i log migracije drže taj prozor malim i vidljivim, a za migraciju koja se radi jednom to je prihvatljiv rizik.
Bug u temeljima, namerno ostavljen na mestu
NutScript, framework na kom server radi, dolazi sa malom bibliotekom za promise-e: deferred-lua, koju je napisao jedan od autora NutScript-a. Promise je priznanica: „evo inventara, čim baza odgovori.“ Koraci se ulančavaju, a svaki korak može da vrati novu priznanicu na koju sledeći korak čeka.
Migracija gepeka naletela je na slučaj koji biblioteka pogrešno obrađuje. Kada korak vrati priznanicu koja je već propala, lanac jednostavno stane. Nema greške, nema stack trace-a, nema kroz šta da se prođe debuggerom: sve što čeka na nju čeka zauvek.
Uzrok su dve linije pogrešnim redom. Biblioteka prvo označi sopstvenu priznanicu kao propalu, a zatim pozove funkciju koja je označava kao propalu i javlja svima koji čekaju. Ta funkcija radi samo sa priznanicama koje još čekaju, vidi da je ova već označena i ne uradi ništa.
-- deferred-lua, inside Promise:_handle: a step handed back another promise,
-- so copy its state.
self.state = value.state
if (value.state == PENDING) then
-- ... wait for it, then pass the result on (this path works)
elseif (value.state == FULFILLED) then
self:_handle(value.value) -- runs everyone waiting
else
self:reject(value.reason) -- does nothing: reject() only acts while
end -- pending, and the state was just copied
-- The fix: treat a failure like the fulfilled branch does.
-- self.reason = value.reason
-- self:_handle(value.reason)- Ispravka ima dve linije i odgovara standardu Promises/A+: ako je priznanica koju ste dobili propala, propadate sa istim razlogom.
- Zajedničku biblioteku nisam patchovao. Promise-i prolaze kroz ceo codebase, a svaki drugi sistem je testiran na postojećem ponašanju; menjati ga ispod servera koji radi uživo značilo bi rizikovati da se pokvari nešto što radi.
- Umesto toga, migracija vraća greške koje se razreše trenutak kasnije. Priznanica koja još čeka ide putem u biblioteci koji radi, pa greška stiže do svih do kojih treba da stigne. To je trebalo samo migraciji.
- Bug je i dalje u biblioteci koju NutScript isporučuje. Oba projekta sam poslao ispravku, testove koji ga hvataju i način da se reprodukuje u igri: deferred-lua #1 · NutScript #179 · testovi.
Brzina: od „poslednji upis pobeđuje“ do modifikatora koji se slažu
Napravljeno, u testiranju
Svaki sistem na serveru direktno je postavljao brzinu igrača. Nošenje mnogo keša, pijanstvo i pogodak tejzerom međusobno su se gazili, i ništa posle toga nije vraćalo ispravnu vrednost.
- Svaki sistem postavlja i briše sopstveni imenovani modifikator. Ako se isto ime postavi ponovo, menja stari umesto da se nagomilava.
- Konačna brzina se iznova računa iz osnovne vrednosti i svih aktivnih modifikatora: množioci se međusobno množe, fiksne korekcije se sabiraju, a rezultat nikad ne pada ispod nule. Pošto redosled nije bitan, uklanjanje jednog efekta nikad ne remeti drugi.
- API se generiše u jednoj petlji za svih osam brzina kretanja koje engine ima, od hodanja do penjanja uz merdevine.
- Stari setteri brzine iz engine-a i dalje rade, ali sada postavljaju osnovnu vrednost i loguju upozorenje sa mestom poziva. Pluginovi koji još nisu prebačeni nastavljaju da rade ispravno, a upozorenja tačno pokazuju šta je ostalo da se migrira.
-- Instead of plugins overwriting each other's speeds, each one registers a
-- named modifier. The same API is generated for every speed the engine has.
local speeds = {
"CrouchedWalkSpeed", "DuckSpeed", "LadderClimbSpeed", "MaxSpeed",
"RunSpeed", "SlowWalkSpeed", "UnDuckSpeed", "WalkSpeed",
}
for _, name in ipairs(speeds) do
local set, rawSet = "Set" .. name, "Set" .. name .. "_Raw"
local getBase, setBase = "GetBase" .. name, "SetBase" .. name
local setMod, clearMod = "Set" .. name .. "Mod", "Clear" .. name .. "Mod"
local update = "Update" .. name
local modsVar, baseVar = name .. "_Mods", name .. "_Base"
-- Keep the engine's setter; only the recompute step calls it.
if (not isfunction(plyMeta[rawSet]) and isfunction(plyMeta[set])) then
plyMeta[rawSet] = plyMeta[set]
end
plyMeta[getBase] = function(ply) --[[ ... base from the player class, cached ... ]] end
plyMeta[setBase] = function(ply, value)
ply[baseVar] = value
ply[update](ply)
end
-- e.g. ply:SetRunSpeedMod("drag_body", -0.4) or ply:SetWalkSpeedMod("stimulant", 0.1, 20)
plyMeta[setMod] = function(ply, id, mult, add)
mult, add = mult or 0, add or 0
assert(id ~= nil and isnumber(mult) and isnumber(add), "Invalid arguments to " .. setMod)
ply[modsVar] = ply[modsVar] or {}
ply[modsVar][id] = { mult, add }
ply[update](ply)
end
plyMeta[clearMod] = function(ply, id)
if (ply[modsVar]) then ply[modsVar][id] = nil end
ply[update](ply)
end
-- Recompute from scratch every time: base, times every multiplier, plus every
-- flat bonus. Clearing a modifier always restores the right speed.
plyMeta[update] = function(ply)
local base = ply[getBase](ply)
if (not isnumber(base)) then return end
local mult, add = 1, 0
for _, m in pairs(ply[modsVar] or {}) do
mult = mult * math.max(0, 1 + m[1])
add = add + m[2]
end
ply[rawSet](ply, math.max(base * mult + add, 0))
end
-- Old code still calls SetRunSpeed(...). It now sets the base value and warns,
-- so modifiers stay applied and plugins can be migrated one at a time.
plyMeta[set] = function(ply, value)
ErrorNoHalt("Warning: " .. set .. " called, use " .. setMod .. " instead.\n")
if (isnumber(value)) then ply[setBase](ply, value) end
end
endVideo (opciono) uskoro
Igrač kog istovremeno usporavaju nošenje keša i pijanstvo, a zatim se oporavi od jednog bez gubljenja drugog.
assets/projects/legacy-rescue/speed-stacking.mp4 (oko 15 sekundi)
Manja spasavanja
- Sinhronizacije inventara i predmeta koje su prepunjavale mrežne bafere prebačene na enkodovane, kompresovane payload-e.
- Kompatibilnost sa MySQL 8.0.
- Prerada borbe prsa u prsa koja je raspetljala redosled hookova za combat logging.
- Definicije predmeta spojene u jedan fajl pomoću konvertera u Python-u, a kasnije ponovo razdvojene.