English
Detailed API reference
Generated from
natives.mdduring docs startup and build. This page includes only the implemented API surface and intentionally excludes the proposed API section.
The generated reference preserves the source wording from the repository reference. Narrative guides and grouped overview pages remain hand-written in this docs site.
Stav API
- Implementováno znamená, že API registruje aktuální C# runtime nebo Lua prelude.
- Návrh – není implementováno znamená, že jde pouze o plánovaný kontrakt. Volání takové funkce v aktuální verzi skončí Lua chybou.
- Serverové operace jsou autoritativní. Klientská data ani klientem zaslané argumenty se nesmí považovat za důvěryhodné.
runtimeIdve tvaruinstance:...neboobject:...platí pouze během aktuálního běhu hry a není určen k persistenci.
Přehled jmenných prostorů (Namespaces)
- Runtime a scheduler
- Eventy a síťová komunikace
- Commands, exports a permissions
- Convar API
- Resource manifest
- MySQL API
- Player API
- Inventory API
- Equipment API
- JSON API
- Storage API
- UI API
- Workflow API
- Quest API
- Recipe API
- Asset API
- Machine & Piece API
- Event Hooks
Runtime a scheduler
Stav: implementováno na klientovi i serveru. Každá resource má vlastní MoonSharp VM, serialized execution queue a scheduler. Callbacky eventů, commandů, timerů a MySQL completion se vykonávají přes runtime kontext resource.
CreateThread(callback)
- Deklarace:
CreateThread(callback: function) -> number - Popis: Naplánuje Lua coroutine a vrátí její task ID. Alias:
Citizen.CreateThread.
Wait(milliseconds)
- Deklarace:
Wait(milliseconds: number) -> void - Popis: Uvolní aktuální coroutine nejméně na zadaný počet milisekund. Lze použít jen uvnitř coroutine, event handleru nebo command callbacku. Alias:
Citizen.Wait.
SetTimeout(milliseconds, callback)
- Deklarace:
SetTimeout(milliseconds: number, callback: function) -> number - Popis: Spustí callback jednou po uplynutí zadané doby a vrátí task ID.
ClearTimeout(taskId)
- Deklarace:
ClearTimeout(taskId: number) -> boolean - Popis: Zruší timeout nebo jinou plánovanou úlohu se zadaným ID.
SetInterval(milliseconds, callback)
- Deklarace:
SetInterval(milliseconds: number, callback: function) -> number - Popis: Opakovaně spouští callback. Další běh je naplánován přes scheduler resource.
ClearInterval(taskId)
- Deklarace:
ClearInterval(taskId: number) -> boolean - Popis: Zruší interval nebo jinou plánovanou úlohu se zadaným ID.
Schedule(expression, callback)
- Deklarace:
Schedule(expression: string, callback: function) -> number - Popis: Registruje cron plán v pěti- nebo šestipoložkovém formátu a vrátí task ID. Alias:
Citizen.Schedule.
lua
CreateThread(function()
while true do
Wait(1000)
print('tick')
end
end)
Schedule('0 */5 * * * *', function()
print('každých pět minut')
end)Všechny naplánované úlohy jsou zrušeny při stopnutí resource. Runtime uplatňuje limity queue, CPU a wakeups; resource proto nesmí používat Wait(0) jako neomezenou update smyčku.
Eventy a síťová komunikace
Stav: implementováno. Názvy vlastních eventů jsou case-insensitive. Handlery se automaticky odstraní při stopnutí resource.
AddEventHandler(eventName, callback)
- Strana: Klient / Server
- Deklarace:
AddEventHandler(eventName: string, callback: function) -> void - Popis: Registruje lokální handler.
RegisterNetEvent(eventName, callback)
- Strana: Klient / Server
- Deklarace:
RegisterNetEvent(eventName: string, callback: function) -> void - Popis: Registruje handler, který smí přijmout lokální i síťové vyvolání. Při síťovém volání obsahuje globální proměnná
sourcepeer ID odesílatele; u lokálního eventu jesource = 0.
TriggerEvent(eventName, ...)
- Strana: Klient / Server
- Deklarace:
TriggerEvent(eventName: string, ...: any) -> void - Popis: Vyvolá lokální event ve stejném procesu.
TriggerServerEvent(eventName, ...)
- Strana: Klient
- Deklarace:
TriggerServerEvent(eventName: string, ...: any) -> void - Popis: Odešle JSON serializované argumenty serveru. Server musí event registrovat přes
RegisterNetEvent.
TriggerClientEvent(eventName, targetPeer, ...)
- Strana: Server
- Deklarace:
TriggerClientEvent(eventName: string, targetPeer: number, ...: any) -> void - Popis: Odešle JSON serializované argumenty cílovému klientovi. Cílový klient musí event registrovat přes
RegisterNetEvent.
lua
-- client.lua
TriggerServerEvent('gear:request', 'weapon')
-- server.lua
RegisterNetEvent('gear:request', function(slot)
local peerId = source
TriggerClientEvent('gear:response', peerId, slot, true)
end)Síťový handler musí validovat source, oprávnění, vzdálenost i všechny argumenty. Registrace eventu sama o sobě neposkytuje autorizaci.
Command.Execute(rawCommand, [sourcePeer])
- Strana: Server
- Deklarace:
Command.Execute(rawCommand: string, sourcePeer?: number) -> void - Popis: Spustí registrovaný serverový příkaz z Lua. Volitelný
sourcePeerurčuje identitu odesílatele pro permission checky a quest reward workflow.
Commands, exports a permissions
RegisterCommand(commandName, callback, [restricted])
- Strana: Klient / Server
- Deklarace:
RegisterCommand(commandName: string, callback: function(source: number, args: table<string>, rawCommand: string), restricted?: boolean | string) -> void - Popis: Registruje Lua příkaz. Stejně jako ve FiveM
restricted = truevyžaduje ACEcommand.<commandName>; textová hodnota určí vlastní ACE. Serverový příkaz není nutné duplikovat na klientovi: neznámý klientský příkaz se automaticky předá serveru, který ověří oprávnění před callbackem.argsje pole indexované od1.
lua
RegisterCommand('spawn_boss', function(source, args, rawCommand)
-- Callback se spustí až po serverovém ACE checku command.spawn_boss.
end, true)FiveM-style pravidla lze zapsat přímo do server.cfg:
ini
add_ace group.admin command allow
add_ace group.moderator command.kick allow
add_principal identifier.steam:76561198000000000 group.adminACE jsou hierarchické: command i command.* povolí například command.spawn_boss. Podporované je allow; deny je odmítnuto s warningem. Stávající permissions.json zůstává podporovaný a pravidla ze server.cfg se k němu přidávají jako runtime overlay.
exports(name, callback)
- Strana: Klient / Server
- Deklarace:
exports(exportName: string, callback: function) -> void - Popis: Registruje export vlastněný aktuální resource.
exports[resourceName][exportName](...)
- Strana: Klient / Server
- Deklarace:
exports[resourceName][exportName](...: any) -> any - Popis: Synchronně zavolá export jiné běžící resource na stejné straně procesu. Při chybě nebo neexistujícím exportu vrací
nila zapíše chybu do logu.
HasPermission(permission)
- Strana: Klient / Server
- Deklarace:
HasPermission(permission: string) -> boolean - Popis: Ověří permission lokálního kontextu (
peerId = 0).
Player.HasPermission(peerId, permission)
- Strana: Server
- Deklarace:
Player.HasPermission(peerId: number, permission: string) -> boolean - Popis: Ověří permission konkrétního připojeného hráče. Použijte ji také uvnitř serverových network eventů, protože klient může event vyvolat bez lokálního command handleru.
IsPlayerAceAllowed(source, ace)
- Strana: Server
- Deklarace:
IsPlayerAceAllowed(source: number, ace: string) -> boolean - Popis: FiveM kompatibilní alias pro autoritativní kontrolu ACE. Grant
*,commandnebocommand.*pokrývá také podřízené ACE jakocommand.mithril_mob.
IsPlayerAdmin()
- Strana: Klient / Server
- Deklarace:
IsPlayerAdmin() -> boolean - Popis: Vrátí, zda má lokální kontext wildcard permission
*.
GetCurrentResourceName()
- Strana: Klient / Server
- Deklarace:
GetCurrentResourceName() -> string - Popis: Vrátí název resource vlastnící aktuální VM.
Convar API
Globální convars se načítají ze serverového server.cfg, resource convars ze souboru resource.cfg uvnitř resource. Direktiva set je server-only, setr se replikuje klientům a sets je secret dostupný pouze interním serverovým subsystémům. Lua getter nikdy nevrací secret hodnotu.
Globální convars
GetConvar(key: string, defaultValue: string) -> stringGetConvarInt(key: string, defaultValue: number) -> numberGetConvarFloat(key: string, defaultValue: number) -> numberGetConvarBool(key: string, defaultValue: boolean) -> booleanSetConvar(key: string, value: string) -> voidSetReplicatedConvar(key: string, value: string) -> void
Convars aktuální resource
GetResourceConvar(key: string, defaultValue: string) -> stringGetResourceConvarInt(key: string, defaultValue: number) -> numberGetResourceConvarFloat(key: string, defaultValue: number) -> numberGetResourceConvarBool(key: string, defaultValue: boolean) -> booleanSetResourceConvar(key: string, value: string) -> voidSetReplicatedResourceConvar(key: string, value: string) -> void
Settery jsou technicky registrované v obou VM, ale pouze server je autoritativní a pouze server může broadcastovat replicated snapshot. Klientské změny jsou lokální, dočasné a nesmí se používat pro gameplay rozhodnutí.
Resource manifest
Každá resource musí obsahovat manifest.lua. Parser používá soft sandbox a podporuje následující direktivy:
name 'resource_name',author 'name',version '1.0.0',description '...'amanifest_version '...',client_script 'client.lua'neboclient_scripts { 'a.lua', 'b.lua' },server_script 'server.lua'neboserver_scripts { 'a.lua', 'b.lua' },file 'data/file.json'nebofiles { 'data/a.json', 'assets/icon.png' },asset_bundle 'assets/content.bundle'neboasset_bundles { 'assets/a.bundle', 'assets/b.bundle' }.
lua
name 'gear_system'
author 'Server Team'
version '1.0.0'
client_script 'client.lua'
server_script 'server.lua'
files {
'locales/en.json',
'locales/cs.json'
}
asset_bundle 'assets/gear_ui.bundle'Asset bundle direktivy automaticky zařadí soubor také do files. Smart Cache počítá hash manifestu, klientských skriptů a synchronizovaných souborů; serverové skripty se klientům neposílají. Vzdálený klient spustí client scripts až po přijetí serverového katalogu, synchronizaci chybějících souborů a ověření hashe.
Při stopnutí resource engine odstraní event handlery, commands, exports, schedulované úlohy, čekající MySQL operace a načtené AssetBundles dané resource.
MySQL API
Strana: pouze Server. API používá pooled MySql.Data připojení a podporuje callback i coroutine .await syntaxi. Connection string je secret server convar a není dostupný Lua skriptům ani klientům.
Konfigurace
ini
sets mysql_connection_string "mysql://user:password@host:3306/database?charset=utf8mb4"
set mysql_slow_query_warning "700"
set mysql_connection_timeout "15"
set mysql_command_timeout "30"
set mysql_pool_size "10"Parametry a výsledky
Pojmenované parametry mohou používat klíče id nebo @id. Poziční parametry jsou souvislé Lua pole od indexu 1 a v SQL odpovídají znakům ?. Oba styly nelze v jednom dotazu míchat. Podporované hodnoty parametrů jsou nil, boolean, number a string.
queryvrací pole řádků,singlevrací první řádek nebonil,scalarvrací první hodnotu nebonil,insertvrací last insert ID,updatevrací počet ovlivněných řádků.
Databázové BIGINT mimo bezpečný Lua rozsah, DECIMAL, datum a čas se vracejí jako string. Binární hodnota se vrací jako Base64 string a SQL NULL jako nil.
Základní operace
Callback forma vrací operation ID a callback přijímá (result, err). .await lze volat jen uvnitř coroutine, event handleru nebo command callbacku; databázovou chybu vyhodí jako Lua error.
MySQL.query(sqlOrStoreId, [params], [callback]) -> operationIdMySQL.query.await(sqlOrStoreId, [params]) -> table<table>MySQL.single(sqlOrStoreId, [params], [callback]) -> operationIdMySQL.single.await(sqlOrStoreId, [params]) -> table | nilMySQL.scalar(sqlOrStoreId, [params], [callback]) -> operationIdMySQL.scalar.await(sqlOrStoreId, [params]) -> any | nilMySQL.insert(sqlOrStoreId, [params], [callback]) -> operationIdMySQL.insert.await(sqlOrStoreId, [params]) -> number | stringMySQL.update(sqlOrStoreId, [params], [callback]) -> operationIdMySQL.update.await(sqlOrStoreId, [params]) -> number | string
lua
local rows = MySQL.query.await('SELECT * FROM players WHERE steam_id = @steamId', {
steamId = Player.GetSteamId(peerId)
})MySQL.prepare
MySQL.prepare(sqlOrStoreId, [params], [callback]) -> operationIdMySQL.prepare.await(sqlOrStoreId, [params]) -> any
Výsledný typ se odvodí z prvního SQL klíčového slova: INSERT vrací ID, UPDATE, DELETE, REPLACE a TRUNCATE vracejí affected rows, ostatní příkazy vracejí pole řádků.
MySQL.rawExecute
MySQL.rawExecute(sqlOrStoreId, parameterSets, [callback]) -> operationIdMySQL.rawExecute.await(sqlOrStoreId, parameterSets) -> any | table<any>
Provede stejný SQL příkaz jednou pro každou tabulku parametrů. Při více sadách vrátí pole výsledků; při jedné sadě přímo jeden výsledek.
MySQL.store(sql)
- Deklarace:
MySQL.store(sql: string) -> number - Popis: Uloží SQL text do paměti aktuální resource a vrátí lokální store ID použitelné místo SQL stringu. Store se odstraní při stopnutí resource.
MySQL.transaction
MySQL.transaction(queries, [sharedParams], [callback]) -> operationIdMySQL.transaction.await(queries, [sharedParams]) -> boolean
queries může být pole SQL stringů/store IDs nebo pole tabulek { query = sqlOrStoreId, values = params }. Pokud položka nemá vlastní values, použijí se sharedParams. Při první chybě proběhne rollback celé transakce.
MySQL.startTransaction
MySQL.startTransaction(callback: function(tx)) -> anyMySQL.startTransaction.await(callback: function(tx)) -> any- Popis: Spustí interaktivní transakci.
tx.await(sqlOrStoreId, [params])provádí jednotlivé kroky na stejném connection/transaction objektu. Callback commitne, pokud doběhne bez chyby a nevrátí explicitněfalse; jinak provede rollback.
Obě varianty mají stejnou await semantiku a musí běžet uvnitř coroutine, event handleru nebo command callbacku.
lua
MySQL.startTransaction.await(function(tx)
local rows = tx.await('SELECT balance FROM accounts WHERE id = @id FOR UPDATE', { id = 1 })
if not rows[1] or rows[1].balance < 10 then
return false
end
tx.await('UPDATE accounts SET balance = balance - 10 WHERE id = @id', { id = 1 })
return true
end)Readiness
MySQL.isReady() -> booleanMySQL.awaitConnection() -> trueMySQL.ready(callback) -> voidMySQL.ready.await() -> true
Čekající operace a transakční session jsou zrušeny při stopnutí resource; pozdní completion se nevrátí do nové generace VM.
1. Player API
Práce s postavou hráče, pozicí, statistikami a herním rozhraním.
Player-target natives kompatibilně přijímají buď původní síťové peerId, nebo explicitní sessionové serverId. Nové scripty by měly preferovat serverId, protože odpovídá tomu, co engine i admin rozhraní ukazuje jako #1, #2, ...
Podporované tvary selektoru:
lua
local serverId = 12
Player.GetName({ serverId = serverId })
Inventory.AddItem({ serverId = serverId }, "Wood", 10, 1)
Equipment.GiveItem({ serverId = serverId }, storedItem, true)
Player.Notify({ serverId = serverId }, "Ahoj", "TopLeft")Status implementace:
[x] Player.GetPos(serverId)
- Strana: Klient / Server
- Deklarace:
Player.GetPos(serverId: number | { serverId: number }) -> { x: number, y: number, z: number } - Popis: Vrátí aktuální souřadnice hráče ve světě. Na klientovi lze použít
0pro lokálního hráče. StaršípeerIdpojmenování zůstává kompatibilní.
[x] Player.SetPos(serverId, x, y, z)
- Strana: Klient / Server
- Deklarace:
Player.SetPos(serverId: number | { serverId: number }, x: number, y: number, z: number) -> void - Popis: Teleportuje hráče na zadanou pozici.
[x] Player.GetHealth(serverId)
- Strana: Klient / Server
- Deklarace:
Player.GetHealth(serverId: number | { serverId: number }) -> number - Popis: Vrátí aktuální počet životů hráče.
[x] Player.SetHealth(serverId, amount)
- Strana: Klient / Server
- Deklarace:
Player.SetHealth(serverId: number | { serverId: number }, amount: number) -> void - Popis: Nastaví aktuální počet životů hráče.
[x] Player.GetStamina(serverId)
- Strana: Klient
- Deklarace:
Player.GetStamina(serverId: number | { serverId: number }) -> number - Popis: Vrátí zbývající výdrž hráče.
[x] Player.SetStamina(serverId, amount)
- Strana: Klient
- Deklarace:
Player.SetStamina(serverId: number | { serverId: number }, amount: number) -> void - Popis: Nastaví zbývající výdrž hráče.
[x] Player.GetName(serverId)
- Strana: Klient / Server
- Deklarace:
Player.GetName(peerId: number | string | { serverId: number } | { peerId: number }) -> string - Popis: Vrátí herní jméno postavy. Holé číslo je kvůli zpětné kompatibilitě pořád interpretované jako původní
peerId; explicitníserverIdpoužívej přes selektor tabulku nebo stringserver:1.
[x] Player.GetSteamId(serverId)
- Strana: Server
- Deklarace:
Player.GetSteamId(peerId: number | string | { serverId: number } | { peerId: number }) -> string - Popis: Vrátí SteamID64 hráče pro ukládání do perzistentních databází/souborů.
[x] Player.GetServerId(playerSelector)
- Strana: Klient / Server
- Deklarace:
Player.GetServerId(playerSelector: number | string | { serverId?: number, peerId?: number }) -> number - Popis: Normalizuje identifikátor hráče na explicitní
serverId. Akceptuje původnípeerId, string ve tvaruserver:12nebopeer:-1471880800, i tabulku seserverIdnebo staršímpeerId.
[x] Player.Notify(...)
- Strana: Klient / Server
- Server:
Player.Notify(peerId: number | string | { serverId: number } | { peerId: number }, message: string, type?: "Center" | "TopLeft") -> void - Klient:
Player.Notify(message: string, type?: "Center" | "TopLeft") -> void - Popis: Zobrazí herní textové hlášení cílovému nebo lokálnímu hráči. Výchozí typ je
"Center". Klientský alias jenotify(message, type?).
[x] Player.PlayEffect(...)
- Strana: Klient / Server
- Server:
Player.PlayEffect(peerId: number | string | { serverId: number } | { peerId: number }, effectPrefab: string, x: number, y: number, z: number) -> void - Klient:
Player.PlayEffect(effectPrefab: string, x: number, y: number, z: number) -> void - Popis: Přehraje vizuální a zvukový efekt na zadaných souřadnicích pro daného hráče. Na serveru se efekt pošle cílovému klientovi přes RPC, na klientovi se prefab spustí lokálně.
[x] Player.GetAll()
- Strana: Server
- Deklarace:
Player.GetAll() -> table<number> - Popis: Vrátí pole původních síťových
peerIdvšech online připojených hráčů. Zůstává kvůli kompatibilitě.
[x] Player.GetAllServerIds()
- Strana: Server
- Deklarace:
Player.GetAllServerIds() -> table<number> - Popis: Vrátí pole explicitních
serverIdvšech online hráčů.
2. Inventory API
Práce s inventářem hráče pro úkoly typu Fetch, obchody a odměny.
Status implementace:
InventoryItem read model nyní vždy obsahuje stabilní runtime itemId, který engine ukládá do item customData pod interním klíčem. itemId je stabilní přes běh hry i serializaci itemu, ale Lua nemá tento interní klíč v customData přímo vystavený; používá samostatné pole itemId.
Inventory.GetItemCount(peerId, prefabName)
- Strana: Klient / Server
- Deklarace:
Inventory.GetItemCount(peerId: number, prefabName: string) -> number - Popis: Vrátí celkový počet kusů zadaného předmětu v inventáři hráče.
Inventory.HasItem(peerId, prefabName, amount)
- Strana: Klient / Server
- Deklarace:
Inventory.HasItem(peerId: number, prefabName: string, amount: number) -> boolean - Popis: Rychlý test, zda má hráč v inventáři alespoň požadovaný počet kusů předmětu.
Inventory.AddItem(peerId, prefabName, amount, [quality])
- Strana: Klient / Server
- Deklarace:
Inventory.AddItem(peerId: number, prefabName: string, amount: number, quality?: number, expectedRevision?: number) -> boolean - Popis: Přidá předmět do inventáře hráče. Vrátí
true, pokud se předmět vešel, jinakfalse. Pokud je zadanáexpectedRevision, operace selže bez změny při nesouladu revize. Na dedicated serveru engine používá pro vzdálené hráče server-owned authoritative inventory mirror a po úspěšné mutaci snapshot synchronizuje zpět klientovi.
Inventory.RemoveItem(peerId, prefabName, amount)
- Strana: Klient / Server
- Deklarace:
Inventory.RemoveItem(peerId: number, prefabName: string, amount: number, expectedRevision?: number) -> boolean - Popis: Odebere zadaný počet kusů itemu z inventáře. Vrátí
true, pokud se odebrání zdařilo. Pokud je zadanáexpectedRevision, operace selže bez částečné změny při nesouladu revize.
Inventory.GetEmptySlots(peerId)
- Strana: Klient / Server
- Deklarace:
Inventory.GetEmptySlots(peerId: number) -> number - Popis: Vrátí počet volných slotů v inventáři.
Inventory.GetAllItems(peerId)
- Strana: Klient / Server
- Deklarace:
Inventory.GetAllItems(peerId: number) -> table<InventoryItem> - Popis: Vrátí kompletní obsah inventáře hráče včetně
itemId, grid pozice a serializovatelných metadat instance.
Inventory.GetItem(peerId, itemId)
- Strana: Klient / Server
- Deklarace:
Inventory.GetItem(peerId: number, itemId: string) -> InventoryItem | nil - Popis: Vrátí konkrétní item instanci podle jejího stabilního
itemId.
Inventory.GetItemAt(peerId, x, y)
- Strana: Klient / Server
- Deklarace:
Inventory.GetItemAt(peerId: number, x: number, y: number) -> InventoryItem | nil - Popis: Vrátí item v konkrétní grid pozici inventáře.
Inventory.FindItems(peerId, [filter])
- Strana: Klient / Server
- Deklarace:
Inventory.FindItems(peerId: number, filter?: string | table) -> table<InventoryItem> - Popis: Vrátí itemy odpovídající filtru. String filtr se bere jako
prefab. Tabulkový filtr podporujeitemId,prefab,itemType,nameContains,equipped,x,y,minCount,maxCount,quality,qualityMinaqualityMax.
Inventory.GetSize(peerId)
- Strana: Klient / Server
- Deklarace:
Inventory.GetSize(peerId: number) -> { width: number, height: number, emptySlots: number } - Popis: Vrátí rozměr inventáře a aktuální počet volných slotů.
Inventory.MoveItem(peerId, itemId, targetX, targetY)
- Strana: Klient / Server
- Deklarace:
Inventory.MoveItem(peerId: number, itemId: string, targetX: number, targetY: number, expectedRevision?: number) -> boolean - Popis: Přesune konkrétní item instanci do cílového slotu. Operace selže, pokud je cíl mimo rozměr inventáře, už je obsazený nebo neodpovídá
expectedRevision.
Inventory.RemoveItemById(peerId, itemId, [amount])
- Strana: Klient / Server
- Deklarace:
Inventory.RemoveItemById(peerId: number, itemId: string, amount?: number, expectedRevision?: number) -> boolean - Popis: Odebere přesně určenou item instanci. Při stackovatelném itemu lze odebrat jen část stacku. Pokud je zadaná
expectedRevision, stale požadavek se odmítne beze změny.
Inventory.UpdateItem(peerId, itemId, patch)
- Strana: Klient / Server
- Deklarace:
Inventory.UpdateItem(peerId: number, itemId: string, patch: table, expectedRevision?: number) -> boolean - Popis: Aplikuje povolené mutace metadat itemu. Podporované klíče jsou
quality,durability,variant,crafterId,crafterName,worldLevelacustomData.
Inventory.SplitStack(peerId, itemId, amount)
- Strana: Klient / Server
- Deklarace:
Inventory.SplitStack(peerId: number, itemId: string, amount: number, expectedRevision?: number) -> InventoryItem | nil - Popis: Oddělí část stacku do nové item instance v prvním volném slotu a vrátí snapshot nově vzniklého stacku. Při nesouladu
expectedRevisionvrátínilbez změny.
Inventory.MergeStacks(peerId, sourceItemId, targetItemId)
- Strana: Klient / Server
- Deklarace:
Inventory.MergeStacks(peerId: number, sourceItemId: string, targetItemId: string, expectedRevision?: number) -> boolean - Popis: Přesune kusy ze zdrojového stacku do cílového, pokud jde o kompatibilní stackovatelný item se stejnými metadaty. Při nesouladu
expectedRevisionselže bez částečné změny.
Inventory.Resize(peerId, width, height, [overflowPolicy])
- Strana: Klient / Server
- Deklarace:
Inventory.Resize(peerId: number, width: number, height: number, overflowPolicy?: string, expectedRevision?: number) -> boolean - Popis: Změní rozměr inventáře. Aktuálně je podporovaná pouze bezpečná politika
"reject", která změnu odmítne, pokud by se některý item ocitl mimo nový grid nebo pokud neodpovídáexpectedRevision. Pro zpětnou kompatibilitu lze jako čtvrtý argument předat rovnouexpectedRevisiona policy zůstane"reject".
Inventory.GetRevision(peerId)
- Strana: Klient / Server
- Deklarace:
Inventory.GetRevision(peerId: number) -> number - Popis: Vrátí monotónně rostoucí revizi inventáře pro optimistic concurrency kontrolu. Každá úspěšná mutace inventáře revizi zvýší o
1; rollback aktivního transaction snapshotu ji vrátí na hodnotu přiBeginTransaction.
Inventory.BeginTransaction(peerId, [expectedRevision])
- Strana: Klient / Server
- Deklarace:
Inventory.BeginTransaction(peerId: number, expectedRevision?: number) -> number | nil - Popis: Zamkne inventář pro aktuální resource, uloží snapshot obsahu a vrátí transaction ID. Pokud už je inventář zamčený jinou resource nebo neodpovídá
expectedRevision, vrátínil. Na dedicated serveru lze transakci otevřít i nad server-owned mirror inventáře vzdáleného hráče.
Inventory.CommitTransaction(transactionId, [expectedRevision])
- Strana: Klient / Server
- Deklarace:
Inventory.CommitTransaction(transactionId: number, expectedRevision?: number) -> boolean - Popis: Ukončí aktivní transaction a uvolní lock. Volitelná
expectedRevisionumožňuje ověřit finální stav před commitem.
Inventory.RollbackTransaction(transactionId)
- Strana: Klient / Server
- Deklarace:
Inventory.RollbackTransaction(transactionId: number) -> boolean - Popis: Obnoví snapshot uložený při
BeginTransaction, vrátí revizi na původní hodnotu a uvolní lock. Session stejné resource se také automaticky rollbacknou při stopnutí resource.
InventoryItem obsahuje itemId, prefab, count, quality, durability, variant, equipped, x, y, name, itemType, armor, durabilityPercent, maxDurability, crafterId, crafterName, worldLevel a customData.
Inventářové transaction session jsou zatím omezené na jeden zamčený hráčský inventář na resource a neřeší ještě multi-inventory batch scénáře ani síťovou obnovu po odpojení hráče.
Container API
API pro vanilla i resource-owned world containery. Identifikátory mají stabilní formát zdo:<userId>:<objectId>. Obsah inventářů je autoritativně uložen v container-authority.json, nebo při inventory_storage=mysql v tabulce vle_container_inventories s JSON recovery cache. World UID je součástí interního storage klíče. ZDO obsah slouží jako runtime replika pro vanilla UI; změny provedené přes UI se podle ZDO.DataRevision importují zpět do externí autority. Read-only discovery funguje na klientu i serveru; mutace zůstávají serverové a na dedikovaném serveru pracují přímo s JSON/ZDO i bez Unity instance containeru.
Server automaticky registruje každý Valheim container nalezený v ZDO databázi, tedy i starší vanilla úložiště bez živého Unity objektu. JSON obsahuje vedle Inventories také registry Containers s identitou, prefabem, pozicí, rozměry, resource ownerem a tagem. Registry, čtení i serverové mutace fungují také pro momentálně odloadované objekty.
Container.SpawnForPlayer(peerId, prefabName, [distance], [width], [height], [tag])
- Strana: Server
- Deklarace:
Container.SpawnForPlayer(peerId: number, prefabName: string, distance?: number, width?: number, height?: number, tag?: string) -> string | nil - Popis: Vytvoří síťový container před hráčem podle serverového character ZDO, nastaví vlastníka resource, tag a rozměry inventáře a vrátí stabilní ID.
Container.GetAll([tag])
- Strana: Klient / Server
- Deklarace:
Container.GetAll(tag?: string) -> table<string> - Popis: Vrátí ID všech dostupných vanilla containerů a containerů vlastněných aktuální resource, volitelně filtrovaných tagem; server používá i ZDO databázi a persistentní registry.
Container.FindNearby(x, y, z, radius, [prefabName], [kind])
- Strana: Klient / Server
- Deklarace:
Container.FindNearby(x: number, y: number, z: number, radius: number, prefabName?: string, kind?: string) -> table<ContainerData> - Popis: Vrátí všechny dostupné containery v okruhu seřazené od nejbližšího.
prefabNamefiltruje napříkladpiece_chest_wood;kindpřijímáany,vanillaneboresource. Výchozíanyzahrnuje vanilla containery a containery aktuální resource, ale ne objekty vlastněné jinou resource.
Container.FindNearest(x, y, z, radius, [prefabName], [kind])
- Strana: Klient / Server
- Deklarace:
Container.FindNearest(x: number, y: number, z: number, radius: number, prefabName?: string, kind?: string) -> ContainerData | nil - Popis: Vrátí nejbližší dostupný container podle stejných filtrů jako
FindNearby, nebonil.
Container.GetData(containerId)
- Strana: Klient / Server
- Deklarace:
Container.GetData(containerId: string) -> table | nil - Popis: Vrátí metadata containeru včetně
id,prefab,kind,resource,tag,ownerSteamId,width,height,count,isInUseaposition.
Container.GetAllItems(containerId)
- Strana: Klient / Server
- Deklarace:
Container.GetAllItems(containerId: string) -> table<InventoryItem> - Popis: Vrátí položky containeru ve stejném formátu jako
Inventory.GetAllItems. Na klientu jde pouze o lokálně replikovaný read-only pohled; autoritativní rozhodnutí a změny musí provést server.
Container.GetRevision(containerId)
- Strana: Server
- Deklarace:
Container.GetRevision(containerId: string) -> number - Popis: Vrátí runtime revizi containeru používanou pro sledování serverových mutací.
Container.AddItem(containerId, prefabName, amount, [quality])
- Strana: Server
- Deklarace:
Container.AddItem(containerId: string, prefabName: string, amount: number, quality?: number) -> boolean - Popis: Přidá item do vanilla containeru nebo containeru aktuální resource a uloží autoritativní snapshot do JSON/MySQL storage. ZDO runtime kopie se aktualizuje pro vanilla UI a síťovou replikaci.
Container.RemoveItemById(containerId, itemIdOrPrefab, [amount])
- Strana: Server
- Deklarace:
Container.RemoveItemById(containerId: string, itemIdOrPrefab: string, amount?: number) -> boolean - Popis: Odebere přesný item nebo část stacku podle stabilního
itemId. Pokud ID neexistuje, argument se použije jako case-insensitive název prefabu a požadované množství se odebere i přes více odpovídajících stacků.
Container.TransferFromPlayer(containerId, peerId, itemId, [amount])
- Strana: Server
- Deklarace:
Container.TransferFromPlayer(containerId: string, peerId: number, itemId: string, amount?: number) -> boolean - Popis: Atomicky přesune item ze server-authoritative inventáře hráče do containeru a synchronizuje hráčův nový stav klientovi.
Container.TransferToPlayer(containerId, peerId, itemId, [amount])
- Strana: Server
- Deklarace:
Container.TransferToPlayer(containerId: string, peerId: number, itemId: string, amount?: number) -> boolean - Popis: Atomicky přesune item z containeru do server-authoritative inventáře hráče a synchronizuje hráčův nový stav klientovi.
Mutace jsou odmítnuty, pokud container vlastní jiná resource. U živé serverové Container instance jsou odmítnuty také během používání hráčem; čistě headless ZDO nemá spolehlivý realtime inUse stav. Vanilla containery bez resource vlastníka a containery aktuální resource lze měnit. Přenos zachovává kvalitu, durability, variantu, crafter metadata a custom data itemu.
Equipment API
Čtení equipnutých slotů a nízkoúrovňové mutace inventáře pro Lua-owned gear systémy. Doporučený model je, že Lua resource drží vlastní JSON databázi hráčů a gearu, zatímco engine poskytuje jen nativní operace pro odebrání equipnutého itemu a jeho vrácení zpět.
Status implementace:
Equipment.GetEquipped(peerId)
- Strana: Klient / Server
- Deklarace:
Equipment.GetEquipped(peerId: number) -> table<EquipmentItem> - Popis: Vrátí seznam aktuálně equipnutých itemů hráče.
Equipment.GetSlotMap(peerId)
- Strana: Klient / Server
- Deklarace:
Equipment.GetSlotMap(peerId: number) -> table - Popis: Vrátí mapu slotů jako
head,chest,legs,shoulder,weapon,offhand,tool,trinket.
Equipment.IsSlotOccupied(peerId, slotName)
- Strana: Klient / Server
- Deklarace:
Equipment.IsSlotOccupied(peerId: number, slotName: string) -> boolean - Popis: Ověří, zda je konkrétní equip slot obsazený.
Equipment.GetArmor(peerId)
- Strana: Klient / Server
- Deklarace:
Equipment.GetArmor(peerId: number) -> number - Popis: Vrátí součet armoru aktuálně equipnutých itemů.
Equipment.TakeEquipped(peerId, slotName)
- Strana: Klient / Server
- Deklarace:
Equipment.TakeEquipped(peerId: number, slotName: string) -> table | nil - Popis: Najde equipnutý item v daném slotu, odebere ho z inventáře a vrátí serializovatelnou Lua tabulku vhodnou pro uložení do vlastní JSON DB resource. Na dedicated serveru se pro vzdálené hráče pracuje nad server-owned authoritative inventory mirrorrem, takže vybavení lze číst a mutovat i bez klientského workaroundu.
Equipment.GiveItem(peerId, item, [equip])
- Strana: Klient / Server
- Deklarace:
Equipment.GiveItem(peerId: number, item: table, equip?: boolean) -> boolean - Popis: Vezme Lua tabulku s item daty, vrátí item do inventáře hráče a volitelně ho rovnou equipne. Pokud je při
equip = truecílový slot obsazený, operace selže. Na dedicated serveru engine po mutaci vzdáleného hráče aktualizuje authoritative mirror a synchronizuje výsledný snapshot klientovi.
EquipmentItem z read API obsahuje itemId, prefab, count, quality, durability, slot, itemType, name, armor, durabilityPercent, maxDurability, equipped, variant, x, y, crafterId, crafterName, worldLevel a customData. Tabulku vrácenou z TakeEquipped lze beze změny předat do GiveItem.
Round-trip nyní zachovává běžný customData dictionary i engine itemId. Metadata externích modů uložená mimo ItemData nebo mimo serializovaný customData slovník ale stále nemusí být bezeztrátová.
Příklad:
lua
local taken = Equipment.TakeEquipped(peerId, "weapon")
if taken then
local db = Storage.ReadJson("data/gear/" .. Player.GetSteamId(peerId) .. ".json") or { slots = {} }
db.slots.weapon = taken
Storage.WriteJson("data/gear/" .. Player.GetSteamId(peerId) .. ".json", db, true)
end
local db = Storage.ReadJson("data/gear/" .. Player.GetSteamId(peerId) .. ".json")
if db and db.slots and db.slots.weapon then
Equipment.GiveItem(peerId, db.slots.weapon, true)
endJSON API
Pomocné funkce pro převod Lua tabulek na JSON a zpět. Hodí se pro persistentní store, síťové payloady i ukládání stavů resource do vlastních struktur.
Status implementace:
Json.Encode(value)
- Strana: Klient / Server
- Deklarace:
Json.Encode(value: any) -> string - Popis: Převede Lua hodnotu na JSON string. Sekvenční tabulky s indexy
1..Nserializuje jako JSON pole, ostatní tabulky jako JSON objekt.
Json.Decode(json)
- Strana: Klient / Server
- Deklarace:
Json.Decode(json: string) -> any | nil - Popis: Načte JSON string zpět do Lua hodnot. JSON objekty vrací jako tabulky s textovými klíči, JSON pole jako tabulky indexované od
1.
Příklad:
lua
local gearStore = {
steamId = "76561198000000000",
slots = {
head = { prefab = "HelmetIron", quality = 2 },
weapon = { prefab = "SwordIron", quality = 3 }
}
}
local json = Json.Encode(gearStore)
local loaded = Json.Decode(json)
print(loaded.slots.head.prefab)Storage API
Jednoduché per-resource ukládání JSON souborů. Cesty jsou vždy sandboxované do aktuální resource složky a API přijímá pouze relativní cesty s příponou .json.
Status implementace:
Storage.ReadJson(path)
- Strana: Klient / Server
- Deklarace:
Storage.ReadJson(path: string) -> any | nil - Popis: Načte JSON soubor z aktuální resource a vrátí jeho obsah jako Lua hodnotu. Pokud soubor neexistuje nebo je neplatný, vrátí
nil.
Storage.WriteJson(path, value, [pretty])
- Strana: Klient / Server
- Deklarace:
Storage.WriteJson(path: string, value: any, pretty?: boolean) -> boolean - Popis: Uloží Lua hodnotu jako JSON do aktuální resource složky. Cílové podadresáře vytvoří automaticky.
Storage.Delete(path)
- Strana: Klient / Server
- Deklarace:
Storage.Delete(path: string) -> boolean - Popis: Smaže JSON soubor z aktuální resource složky.
Příklad persistentního gear store:
lua
local steamId = Player.GetSteamId(peerId)
local path = "data/gear/" .. steamId .. ".json"
local gear = Storage.ReadJson(path) or {
steamId = steamId,
slots = {}
}
gear.slots.head = { prefab = "HelmetIron", quality = 2 }
Storage.WriteJson(path, gear, true)UI API
Klientské UI primitivum pro Lua resources. Engine pouze renderuje panel; obsah, strukturu řádků i kdy se panel zobrazí nebo skryje řídí samotný Lua resource.
Status implementace:
UI.ShowPanel(panelId, definition)
- Strana: Klient
- Deklarace:
UI.ShowPanel(panelId: string, definition: table) -> boolean - Popis: Zobrazí nebo přepíše overlay panel podle identifikátoru.
definitionpodporuje klíčetitle,subtitle,accent,width,anchor(left,centerneboright) arows. Řádek s číselnýmprogressv rozsahu0..1vykreslí pod textem progress bar; opakované volání se stejnýmpanelIdpanel plynule aktualizuje.
Podporovaná struktura definition:
lua
{
title = "Detached Gear",
subtitle = "Stored: 3 | Armor now: 18",
accent = "#c96f2d",
width = 396,
rows = {
{
label = "Head",
value = "HelmetIron Q2",
note = "Equipped now: empty",
filled = true,
actionLabel = "Equip",
actionEvent = "gear:equip",
actionValue = "head"
},
{ label = "Weapon", value = "SwordIron", note = "Equipped now: SwordBronze", filled = true },
{ label = "Crafting", value = "65%", note = "1.1 s remaining", progress = 0.65 }
}
}UI.HidePanel(panelId)
- Strana: Klient
- Deklarace:
UI.HidePanel(panelId: string) -> boolean - Popis: Skryje dříve zobrazený overlay panel.
Pokud řádek obsahuje actionEvent, kliknutí vyvolá lokální TriggerEvent(actionEvent, actionValue). Resource musí příslušný handler registrovat sama.
Universal Window API
Strana: pouze Klient. Univerzální IMGUI window runtime pro pokročilejší okna s vlastním pozadím, ikonami itemů, scroll oblastmi a akcemi.
Status implementace:
UI.OpenWindow(windowId, definition)
- Strana: Klient
- Deklarace:
UI.OpenWindow(windowId: string, definition: table) -> boolean - Popis: Otevře nebo přepíše univerzální okno.
definitionpodporuje klíčetitle,namespace,anchor(left,center,right),x,y,width,height,scale(0.6–1.6),draggable,resizable,rememberLayout,closable,focusable,skin,tokens,accent,backgroundResource,backgroundPath,model(mapa klíč→hodnota pro{placeholders}v textech) anodes(strom uzlů).
Umístění okna: anchor = "center" okno vystředí a ignoruje x/y. U left/right se x ignoruje (okno se přichytí k okraji) a y určuje vertikální pozici v pixelech od horního okraje. Pro libovolné umístění použij libovolnou jinou hodnotu anchoru (nebo ho vynech a nech default "center" nepoužitý přes x/y — viz příklad níže), pak se okno umístí přesně na x, y v pixelech.
Focusable okna: výchozí je focusable = true — okno odemkne kurzor a blokuje ovládání postavy. Nastavením focusable = false vytvoříš pasivní overlay (např. tracker v rohu obrazovky), který kurzor neodemkne a hru neblokuje.
Layout a skin: rememberLayout = true ukládá pozici, velikost a scale pod kombinací namespace + windowId; resizable = true zapne resize handle. Presety classic, parchment, minimal lze přepsat mapou tokens: panel, titleBar, accent, titleText, headerText, text, mutedText, buttonText.
Podporované typy uzlů (type):
| Typ | Popis |
|---|---|
header | Tučný nadpis, text |
text / label | Text, text |
note | Menší poznámkový text |
button | Tlačítko; klik zavolá action s actionValue |
spacer | Vertikální mezera (height) |
separator | Oddělovací čára |
image | Obrázek z iconPrefab (ikona itemu) nebo backgroundResource + backgroundPath |
scroll | Scroll oblast s children |
columns | Horizontální rozložení children |
backgroundResource je název resource, ze které se načte PNG (backgroundPath je relativní cesta uvnitř resource adresáře, např. assets/panel.png). Klik na button vyvolá lokální event ui.action s argumenty (windowId, action, actionValue, jsonPayload).
Příklad — modální okno s vlastním pozadím:
lua
UI.OpenWindow("quest.journal", {
title = "Quest Journal",
width = 760,
height = 540,
scale = 0.9,
resizable = true,
rememberLayout = true,
skin = "parchment",
tokens = { accent = "#d8a83e", text = "#34200d" },
backgroundResource = "quest_panel",
backgroundPath = "assets/journal_bg.png",
model = { questCount = "11/25" },
nodes = {
{ type = "header", text = "Quests: {questCount}" },
{
type = "scroll", id = "list", height = 400,
children = {
{ type = "button", text = "Hour of Reckoning", action = "select", actionValue = "hour_of_reckoning" }
}
},
{ type = "image", iconPrefab = "SwordIron", width = 64, height = 64 }
}
})Příklad — malý tracker v pravém horním rohu bez focusu (hra běží dál, kurzor se neodemkne):
lua
UI.OpenWindow("quest.tracker", {
title = "Tracked",
anchor = "right",
y = 120,
width = 320,
height = 220,
closable = false,
focusable = false,
nodes = {
{ type = "header", text = "Aktivní questy" },
{ type = "text", text = "● Základní řemeslo" },
{ type = "note", text = "Vyrob dřevěné kladivo (0/1)" }
}
})UI.CloseWindow(windowId)
- Strana: Klient
- Deklarace:
UI.CloseWindow(windowId: string) -> boolean - Popis: Zavře dříve otevřené univerzální okno.
UI.WindowExists(windowId)
- Strana: Klient
- Deklarace:
UI.WindowExists(windowId: string) -> boolean - Popis: Vrátí
true, pokud je okno aktuálně otevřené.
Příklad:
lua
UI.ShowPanel("gear.main", {
title = "Detached Gear",
subtitle = "Lua JSON database",
rows = {
{ label = "Head", value = "HelmetIron", note = "Equipped now: empty", filled = true }
}
})Workflow API
Serverové API pro registraci uzlů do WebAdmin Visual Flow Builderu. Uzel zaregistrovaný resource se objeví v browser editoru spolu s built-in uzly a může poskytovat vlastní titul, kategorii, šablonu Lua kódu a popis.
Status implementace:
Workflow.RegisterNode(definition)
- Strana: Server
- Deklarace:
Workflow.RegisterNode(definition: table) -> boolean - Popis: Zaregistruje custom Webflow uzel pro aktuální resource.
definitionmusí obsahovat alespoňidatitle; volitelné klíče jsoucategory,kind,description,handler,templateasubtitle.idje lokální pro resource, ale ve WebAdmin katalogu se publikuje i jako qualified IDresourceName:id.
Workflow.UnregisterNode(localId)
- Strana: Server
- Deklarace:
Workflow.UnregisterNode(localId: string) -> boolean - Popis: Odebere dříve registrovaný custom uzel aktuální resource z Webflow katalogu.
Workflow.GetNodes()
- Strana: Server
- Deklarace:
Workflow.GetNodes() -> table<WorkflowNode> - Popis: Vrátí katalog built-in i resource-local uzlů viditelných pro aktuální resource. Každý záznam obsahuje
resource,id,qualifiedId,title,category,kind,description,handler,template,subtitleabuiltIn.
Příklad:
lua
Workflow.RegisterNode({
id = "grant_starter_kit",
title = "Grant starter kit",
category = "Inventory",
kind = "action",
description = "Adds starter gear to the triggering player.",
handler = "grantStarterKit",
template = "local target = sourcePeer\nInventory.AddItem(target, 'Hammer', 1, 1)",
subtitle = "Hammer + starter food"
})
for _, node in ipairs(Workflow.GetNodes()) do
print(node.qualifiedId, node.title)
endQuest API
Server-authoritativní data-driven quest systém. Definice questů, objektivů a rewardů se načítají z MySQL catalogu; per-player stav se ukládá do MySQL tabulek. Systém je vypnutelný convarmi a vyžaduje funkční MySQL.
Konfigurace v server.cfg:
ini
sets mysql_connection_string "mysql://user:password@host:3306/database?charset=utf8mb4"
set quests_enabled "true"
set quest_require_mysql "true"
set quest_catalog_namespace "default"
set quest_catalog_channel "live"
set quest_table_prefix "vle_quest_"Při startu serveru (nebo po reloadcfg) engine založí tabulky {prefix}catalogs, {prefix}definitions, {prefix}objectives, {prefix}rewards, {prefix}player_quests a {prefix}player_tracked_quests a načte aktivní quest definice pro zvolený namespace/channel. Stav lze sledovat v logu ([Quest] ...).
Status implementace:
Všechny operace jsou asynchronní a výsledek předávají volitelnému callbacku jako (success: bool, payload: string, error: string). payload u Quest.GetJournal je JSON serializovaný journal snapshot.
Quest.GetJournal(peerId, [callback])
- Strana: Server
- Deklarace:
Quest.GetJournal(peerId: number, callback?: function) -> true - Popis: Načte journal hráče. Callback dostane JSON payload s hráčem a seznamem questů (
quests[].questKey,titleKey,category,status,tracked,iconPrefab,objectives,rewards). Stavready_to_claimznamená, že vestavěný journal nabídne serverově ověřenou akci Complete Quest.
lua
Quest.GetJournal(sourcePeer, function(success, payload, error)
if not success then
print('journal failed: ' .. error)
return
end
local journal = Json.Decode(payload)
print('quests: ' .. tostring(#journal.quests))
end)Quest.Assign(peerId, questKey, [callback])
- Strana: Server
- Deklarace:
Quest.Assign(peerId: number, questKey: string, callback?: function) -> true - Popis: Přiřadí quest hráči (vytvoří
player_questszáznam ve stavuactive), pokud ho ještě nemá aktivní/dokončený.
Quest.Abandon(peerId, questKey, [callback])
- Strana: Server
- Deklarace:
Quest.Abandon(peerId: number, questKey: string, callback?: function) -> true - Popis: Označí quest jako
abandoneda zároveň ho odebere z tracked seznamu.
Quest.Track(peerId, questKey, [tracked], [callback])
- Strana: Server
- Deklarace:
Quest.Track(peerId: number, questKey: string, tracked?: bool, callback?: function) -> true - Popis: Připne (
tracked = true, výchozí) nebo odepne (tracked = false) quest v trackeru. Funguje jen pro questy, které má hráč vplayer_quests.
Quest.Complete(peerId, questKey, [callback])
- Strana: Server
- Deklarace:
Quest.Complete(peerId: number, questKey: string, callback?: function) -> true - Popis: Autoritativně dokončí aktivní quest hráče: nastaví stav
completed(u repeatable questůcooldownscooldown_until_unix), zvýšícompleted_count, odebere quest z trackeru a vykoná reward definice z MySQL (notify,give_item,command). Po dokončení vyvolá lokální server eventquest.completeds argumenty(peerId, steamId, playerName, questKey).
Quest.Fail(peerId, questKey, [callback])
- Strana: Server
- Deklarace:
Quest.Fail(peerId: number, questKey: string, callback?: function) -> true - Popis: Označí aktivní quest jako
failed. Hráč ho může znovu přijmout přesQuest.Assign.
Quest.ReportSignal(peerId, signalKey, [payload])
- Strana: Server
- Deklarace:
Quest.ReportSignal(peerId: number, signalKey: string, payload?: table) -> boolean - Popis: Vstřikuje vlastní signál do quest enginu. Objectives se shodují přes
signal_keyafilters_jsonporovnaný protipayload(string hodnoty, case-insensitive). Engine pak posune progress aktivním questům hráče a při splnění všech objectives nastaví stavready_to_claim; rewardy vydá až následná claim akce hráče ve vestavěném journalu.
lua
Quest.ReportSignal(sourcePeer, 'custom.altar_used', { altarPrefab = 'piece_offering' })Vestavěné gameplay signály
Engine automaticky routuje server-side eventy do quest objectives. Podporované signal_key hodnoty a klíče pro filters_json:
| Signal | Payload klíče pro filtry |
|---|---|
player.crafted | itemPrefab, stationPrefab |
player.killed_entity | victimPrefab, victimName, deathReason |
container.items_looted | containerPrefab, mode |
player.item_picked_up | itemPrefab |
trader.item_bought | traderPrefab, itemPrefab |
trader.item_sold | traderPrefab, itemPrefab |
player.died_detail | deathReason, killerPrefab |
Progress objective se navyšuje o amount z payloadu (výchozí 1) a je omezen na target_count. Po každém progressu engine pošle VLua_QuestProgressDelta; vestavěný tracker se aktualizuje bez plného reloadu a klient publikuje lokální event quest.progress(questKey, objectiveKey, progress, target). Stavový přechod následně pošle čerstvý journal snapshot.
Reward kinds v MySQL
reward_kind | payload_json |
|---|---|
notify | { "message": "...", "kind": "TopLeft" } — podporuje tokeny {playerName}, {steamId}, {peerId}, {questId}, {questTitle} |
give_item | { "itemPrefab": "Coins", "amount": 25, "quality": 1 } |
command | { "command": "say {playerName} dokončil {questTitle}" } — spouští se na serveru se stejnými tokeny |
Pokud give_item odmítne plný inventář, reward se uloží do {prefix}player_pending_rewards. Při dalším journal syncu se atomicky rezervuje a zkusí znovu; každý výsledek se zapisuje do {prefix}reward_audit.
Recipe API
Správa crafting receptů přes Lua. Recepty lze číst i měnit za běhu, včetně přiřazení crafting station, takže se dají skládat více-krokové výrobní řetězce ve stylu navazujících strojů.
Status implementace:
Recipe.Get(itemPrefab)
- Strana: Klient / Server
- Deklarace:
Recipe.Get(itemPrefab: string) -> table | nil - Popis: Vrátí definici receptu pro výsledný item prefab, nebo
nil, pokud neexistuje.
Recipe.GetAll()
- Strana: Klient / Server
- Deklarace:
Recipe.GetAll() -> table<table> - Popis: Vrátí seznam všech aktuálně registrovaných receptů v
ObjectDB.
Recipe.Upsert(itemPrefab, definition)
- Strana: Klient / Server
- Deklarace:
Recipe.Upsert(itemPrefab: string, definition: table) -> boolean - Popis: Vytvoří nový recept nebo přepíše existující recept pro výsledný item.
Podporovaná struktura definition:
lua
{
amount = 1,
enabled = true,
qualityResultAmountMultiplier = 1.0,
minStationLevel = 0,
requireOnlyOneIngredient = false,
noCraftOnlyUpgrade = false,
craftingStation = "piece_workbench",
repairStation = "piece_workbench",
resources = {
{ item = "Wood", amount = 10, amountPerLevel = 0, upgraderResource = false, recover = true },
{ item = "Stone", amount = 2 }
}
}craftingStationarepairStationočekávají prefab name objektu seCraftingStationkomponentou.resourcesje povinné pole ingrediencí; lze použít klíčitemneboprefab.
Recipe.SetEnabled(itemPrefab, enabled)
- Strana: Klient / Server
- Deklarace:
Recipe.SetEnabled(itemPrefab: string, enabled: boolean) -> boolean - Popis: Zapne nebo vypne existující recept bez přepsání ostatních parametrů.
Recipe.Remove(itemPrefab)
- Strana: Klient / Server
- Deklarace:
Recipe.Remove(itemPrefab: string) -> boolean - Popis: Odebere recept z
ObjectDB.
Asset API
Práce s Unity objekty z Lua. API pokrývá jak lookup existujících herních prefabů z ZNetScene a ObjectDB, tak načítání vlastních AssetBundle souborů z resource složky. Resource sync nyní přenáší doplňkové soubory binárně přes base64, takže bundle soubory mohou být součástí files { ... } v manifestu.
Manifest může nově používat i explicitní direktivy asset_bundle 'assets/machines.bundle' nebo asset_bundles { 'a.bundle', 'b.bundle' }. Tyto cesty se automaticky zařadí do sync/hash pipeline i do interní evidence resource.
Síťové prefaby, itemy a moby deklarujte přímo v manifest.lua. Engine tyto deklarace automaticky aplikuje na serveru i klientu před spuštěním jejich skriptů. Singulární direktivy jsou network_prefab, bundle_item, derived_item a derived_mob; množné varianty přijímají pole definic:
lua
network_prefabs {
{
bundle = 'assets/content.bundle',
asset = 'assets/content/vein.prefab',
persistent = true
},
{
bundle = 'assets/content.bundle',
asset = 'assets/content/rock.prefab',
persistent = true
}
}
bundle_items {{
bundle = 'assets/content.bundle',
asset = 'assets/content/ore.prefab',
persistent = true
}}
derived_items {{
base = 'SwordBlackmetal',
prefab = 'MySword',
persistent = true,
name = 'My Sword',
damage = { slash = 100 },
icons = { { file = 'assets/my_sword.png' } },
recipe = {
craftingStation = 'forge',
resources = {
{ item = 'Iron', amount = 10 }
}
}
}}
derived_mobs {{
base = 'Greydwarf',
prefab = 'MyGreydwarf',
persistent = true,
name = 'My Greydwarf',
health = 200,
texture = { file = 'assets/my_greydwarf.png', property = '_MainTex' },
loot = {
{ item = 'MyOre', min = 1, max = 3, chance = 0.75, levelMultiplier = true }
}
}}recipe uvnitř derived_item je volitelné. server.lua a client.lua už stejný obsah znovu neregistrují.
Status implementace:
Asset.HasPrefab(prefabName)
- Strana: Klient / Server
- Deklarace:
Asset.HasPrefab(prefabName: string) -> boolean - Popis: Ověří, zda je prefab dostupný v načtené scéně nebo item databázi hry.
Asset.GetPrefabInfo(prefabName)
- Strana: Klient / Server
- Deklarace:
Asset.GetPrefabInfo(prefabName: string) -> table | nil - Popis: Vrátí metadata o prefabu: jméno, komponenty, tag, layer a informaci, zda obsahuje
ZNetView.
Asset.Instantiate(prefabName, x, y, z, [rotY])
- Strana: Server
- Deklarace:
Asset.Instantiate(prefabName: string, x: number, y: number, z: number, rotY?: number) -> string - Popis: Vytvoří instanci existujícího prefabu a vrátí runtime ID ve tvaru
object:12345.
Asset.Destroy(runtimeId)
- Strana: Server
- Deklarace:
Asset.Destroy(runtimeId: string) -> boolean - Popis: Zničí dříve vytvořenou nebo nalezenou runtime instanci objektu.
Asset.GetData(runtimeId)
- Strana: Klient / Server
- Deklarace:
Asset.GetData(runtimeId: string) -> table | nil - Popis: Vrátí metadata o world instanci: prefab, active, position, rotation, scale, komponenty a
hasZNetView.
Asset.FindInstances([prefabName])
- Strana: Klient / Server
- Deklarace:
Asset.FindInstances(prefabName?: string) -> table<string> - Popis: Vrátí runtime ID všech nalezených
GameObjectinstancí, volitelně filtrovaných podle prefabu.
Asset.SetActive(runtimeId, active)
- Strana: Klient / Server
- Deklarace:
Asset.SetActive(runtimeId: string, active: boolean) -> boolean - Popis: Zapne nebo vypne konkrétní world instanci objektu.
Asset.GetPosition(runtimeId)
- Strana: Klient / Server
- Deklarace:
Asset.GetPosition(runtimeId: string) -> { x: number, y: number, z: number } | nil - Popis: Vrátí pozici world instance.
Asset.SetPosition(runtimeId, x, y, z)
- Strana: Klient / Server
- Deklarace:
Asset.SetPosition(runtimeId: string, x: number, y: number, z: number) -> boolean - Popis: Nastaví pozici world instance.
Asset.GetRotation(runtimeId)
- Strana: Klient / Server
- Deklarace:
Asset.GetRotation(runtimeId: string) -> { x: number, y: number, z: number } | nil - Popis: Vrátí Euler rotaci objektu ve stupních.
Asset.SetRotation(runtimeId, x, y, z)
- Strana: Klient / Server
- Deklarace:
Asset.SetRotation(runtimeId: string, x: number, y: number, z: number) -> boolean - Popis: Nastaví Euler rotaci objektu ve stupních.
Asset.GetScale(runtimeId)
- Strana: Klient / Server
- Deklarace:
Asset.GetScale(runtimeId: string) -> { x: number, y: number, z: number } | nil - Popis: Vrátí
localScaleworld instance.
Asset.SetScale(runtimeId, x, [y], [z])
- Strana: Klient / Server
- Deklarace:
Asset.SetScale(runtimeId: string, x: number, y?: number, z?: number) -> boolean - Popis: Nastaví
localScaleobjektu. Při zadání jenxse použije uniformní škálování.
Asset.GetComponents(runtimeId)
- Strana: Klient / Server
- Deklarace:
Asset.GetComponents(runtimeId: string) -> table<string> - Popis: Vrátí seznam názvů Unity komponent na objektu.
Asset.HasComponent(runtimeId, componentName)
- Strana: Klient / Server
- Deklarace:
Asset.HasComponent(runtimeId: string, componentName: string) -> boolean - Popis: Ověří, zda objekt obsahuje komponentu se zadaným názvem typu.
Ukázka:
lua
if Asset.HasPrefab('vfx_Place_stone_wall_2x1') then
local fx = Asset.Instantiate('vfx_Place_stone_wall_2x1', 10, 25, 30, 0)
local info = Asset.GetData(fx)
print(('Spawned asset %s with %d components'):format(info.prefab, #info.components))
endAssetBundle.Load(relativePath)
- Strana: Klient / Server
- Deklarace:
AssetBundle.Load(relativePath: string) -> boolean - Popis: Načte bundle soubor relativně k aktuálnímu resource adresáři a uloží ho do cache daného resource.
AssetBundle.Unload(relativePath, [unloadAllLoadedObjects])
- Strana: Klient / Server
- Deklarace:
AssetBundle.Unload(relativePath: string, unloadAllLoadedObjects?: boolean) -> boolean - Popis: Uvolní načtený asset bundle z cache resource.
AssetBundle.GetDeclared()
- Strana: Klient / Server
- Deklarace:
AssetBundle.GetDeclared() -> table<string> - Popis: Vrátí seznam bundle cest deklarovaných v manifestu aktuálního resource.
AssetBundle.GetLoaded()
- Strana: Klient / Server
- Deklarace:
AssetBundle.GetLoaded() -> table<string> - Popis: Vrátí relativní cesty všech bundle souborů aktuálně načtených pro běžící resource.
AssetBundle.GetAssetNames(relativePath)
- Strana: Klient / Server
- Deklarace:
AssetBundle.GetAssetNames(relativePath: string) -> table<string> - Popis: Vrátí asset names dostupné v daném bundle.
AssetBundle.GetAssetInfo(relativePath, assetName)
- Strana: Klient / Server
- Deklarace:
AssetBundle.GetAssetInfo(relativePath: string, assetName: string) -> table | nil - Popis: Vrátí metadata assetu v bundle, včetně typu a komponent pokud jde o
GameObjectprefab.
AssetBundle.RegisterNetworkPrefab(relativePath, assetName, [persistent])
- Strana: Klient / Server
- Deklarace:
AssetBundle.RegisterNetworkPrefab(relativePath: string, assetName: string, persistent?: boolean) -> boolean - Popis: Načte
GameObjectz bundle a zaregistruje ho pod jeho prefab názvem do síťové scény. Prefab musí mítZNetViewna kořenovém objektu.persistentje ve výchozím stavutrue. - Lifecycle: Preferujte deklaraci
network_prefabv manifestu; engine ji provede na serveru i klientu před jejich skripty. Při zastavení resource engine odstraní její prefaby zeZNetScenea itemy zObjectDB; následný start nebo restart proto může pod stejným názvem zaregistrovat novou verzi prefabu. - Kolize: Registrace selže, pokud stejný název nebo stable hash už používá hra nebo jiný resource.
World.SpawnNetworked(prefabName, x, y, z, [rotY])
- Strana: Server
- Deklarace:
World.SpawnNetworked(prefabName: string, x: number, y: number, z: number, rotY?: number) -> string - Popis: Vytvoří síťovou instanci prefabu registrovaného aktuálním resource. Vrací persistentní ID ve tvaru
zdo:userId:objectId, nebo prázdný řetězec při chybě. - Oprávnění: Resource může vytvářet pouze prefaby, které sama zaregistrovala.
Zpětně kompatibilní ruční registrace ve skriptu:
lua
local registered = AssetBundle.RegisterNetworkPrefab(
'assets/gold_mining.bundle',
'assets/goldvein.prefab',
true
)Serverový spawn:
lua
local veinId = World.SpawnNetworked('GoldVein', 10, 25, 30, 90)
if veinId == '' then
print('[gold_mining] GoldVein spawn failed')
endWorld.DestroyNetworked(zdoId)
- Strana: Server
- Deklarace:
World.DestroyNetworked(zdoId: string) -> boolean - Popis: Smaže persistentní síťový objekt podle ID vráceného z
World.SpawnNetworked. - Oprávnění: Resource může smazat pouze objekty vytvořené z prefabů, které sama zaregistrovala.
lua
local removed = World.DestroyNetworked('zdo:123456789:42')AssetBundle.RegisterItem(relativePath, assetName, [persistent])
- Strana: Klient / Server
- Deklarace:
AssetBundle.RegisterItem(relativePath: string, assetName: string, persistent?: boolean) -> boolean - Popis: Zaregistruje bundle prefab s kořenovými komponentami
ItemDropaZNetViewdoObjectDBiZNetScene. Díky tomu lze item používat v inventáři, receptech a jako síťový world drop. - Lifecycle: Preferujte deklaraci
bundle_itemv manifestu; engine ji provede na obou stranách. Při zastavení resource se item odstraní zObjectDBiZNetScene, takže restart resource může načíst jeho novou verzi bez restartu hry.
lua
local registered = AssetBundle.RegisterItem(
'assets/gold_mining.bundle',
'assets/goldore.prefab',
true
)Item.RegisterDerived(basePrefabName, prefabName, definition, [persistent])
- Strana: Klient / Server
- Deklarace:
Item.RegisterDerived(basePrefabName: string, prefabName: string, definition: table, persistent?: boolean) -> boolean - Popis: Vytvoří vlastní síťový item jako runtime kopii existujícího vanilla itemu. Klon zdědí model, animace, útoky a ostatní item data. Definice může přepsat texty, ikony i bojové statistiky.
- Lifecycle: Preferujte deklaraci
derived_itemv manifestu; engine ji provede na obou stranách a může současně zaregistrovat vnořenýrecipe. Runtime klon a recepty, které na něj odkazují, se odstraní při zastavení resource.
Podporované klíče definition:
name,descriptionicons = { { file = "assets/icon.png" }, ... }pro PNG přímo v resourceicons = { { bundle = "cesta", asset = "assetName" }, ... }pro Sprite z AssetBundledamageadamagePerLevel:generic,blunt,slash,pierce,chop,pickaxe,fire,frost,lightning,poison,spiritmaxDurability,durabilityPerLevel,blockPower,blockPowerPerLeveldeflectionForce,deflectionForcePerLevel,timedBlockBonus,attackForceattackStaminaModifier,backstabBonus,movementModifier,weight,value
PNG cesta musí být relativní k aktuální resource, soubor musí být uveden v manifestu přes file, mít nejvýše 8 MB a rozměry nejvýše 2048×2048. Dynamické textury a sprity engine uvolní při zastavení resource.
lua
local registered = Item.RegisterDerived('SwordBlackmetal', 'VLE_MithrilSword', {
name = 'Mithril Sword',
description = 'A light mithril blade.',
icons = {
{ file = 'assets/mithril_sword.png' }
},
damage = { slash = 110, spirit = 15 },
maxDurability = 250,
movementModifier = -0.03
}, true)Mob.RegisterDerived(basePrefabName, prefabName, definition, [persistent])
- Strana: Klient / Server
- Deklarace:
Mob.RegisterDerived(basePrefabName: string, prefabName: string, definition: table, persistent?: boolean) -> boolean - Popis: Vytvoří síťového moba jako runtime kopii existujícího prefabu s komponentami
CharacteraZNetView. Klon zachová model, skeleton, animace, AI a útoky základního moba. - Lifecycle: Preferujte
derived_mobneboderived_mobsv manifestu. Klonované materiály, PNG textura a prefab se odstraní při zastavení resource.
Podporované klíče definition:
name,health,factionwalkSpeed,speed,runSpeed,turnSpeedfleeIfLowHealth,viewRange,hearRangetolerateWater,tolerateFire,tolerateSmoke,tolerateTartexture = { file = "assets/mob.png", property = "_MainTex" }loot = { { item, min, max, chance, levelMultiplier, onePerPlayer }, ... }
loot nahrazuje původní drop tabulku. Hodnota chance je v rozsahu 0 až 1. Item musí být při registraci dostupný v ObjectDB nebo ZNetScene. PNG musí být uvedené přes file v manifestu, mít nejvýše 16 MB a rozměry nejvýše 4096×4096.
lua
derived_mobs {{
base = 'Greydwarf',
prefab = 'VLE_MithrilGreydwarf',
persistent = true,
name = 'Mithril Greydwarf',
health = 180,
texture = { file = 'assets/mithril_greydwarf.png' },
loot = {
{ item = 'VLE_MithrilOre', min = 1, max = 3, chance = 1 }
}
}}World.SpawnNetworkedForPlayer(prefabName, peerId, [distance])
- Strana: Server
- Deklarace:
World.SpawnNetworkedForPlayer(prefabName: string, peerId: number, distance?: number) -> string - Popis: Vytvoří prefab vlastněný aktuální resource 1 až 20 metrů před hráčem podle jeho serverové ZDO pozice a rotace. Objekt otočí směrem k hráči a vrátí jeho
zdoId; při chybě vrátí prázdný řetězec.
lua
RegisterNetEvent('my_resource:spawn_mob', function()
local mobId = World.SpawnNetworkedForPlayer('MyGreydwarf', source, 3)
end)AssetBundle.Instantiate(relativePath, assetName, x, y, z, [rotY])
- Strana: Server
- Deklarace:
AssetBundle.Instantiate(relativePath: string, assetName: string, x: number, y: number, z: number, rotY?: number) -> string - Popis: Načte prefab
GameObjectz bundle a vytvoří jeho world instanci. Vrací runtime IDobject:....
Ukázka s vlastním bundle:
lua
if AssetBundle.Load('assets/machines.bundle') then
for _, assetName in ipairs(AssetBundle.GetAssetNames('assets/machines.bundle')) do
print('bundle asset: ' .. assetName)
end
local machineId = AssetBundle.Instantiate('assets/machines.bundle', 'assets/prefabs/lua_crusher.prefab', 5, 20, 5, 90)
Asset.SetScale(machineId, 1.2)
Asset.SetActive(machineId, true)
local machine = Asset.GetData(machineId)
print(('spawned custom machine %s'):format(machine.prefab))
endMachine & Piece API
Primitiva pro skládání vlastních výrobních řetězců nad existujícími world objekty. Runtime instance ve světě se identifikují přes řetězec ve tvaru instance:12345; ten je platný jen pro aktuální běh hry.
Status implementace:
Piece.Spawn(prefabName, x, y, z, [rotY])
- Strana: Server
- Deklarace:
Piece.Spawn(prefabName: string, x: number, y: number, z: number, rotY?: number) -> string - Popis: Vytvoří world instanci prefabu obsahujícího komponentu
Piecea vrátí její runtime ID.
Piece.GetAll([prefabName])
- Strana: Klient / Server
- Deklarace:
Piece.GetAll(prefabName?: string) -> table<string> - Popis: Vrátí runtime ID všech aktuálně nalezených
Pieceinstancí, volitelně filtrovaných podle prefabu.
Piece.GetData(runtimeId)
- Strana: Klient / Server
- Deklarace:
Piece.GetData(runtimeId: string) -> table | nil - Popis: Vrátí metadata o konkrétní world instanci: prefab, jméno, description, position, enabled, category a crafting station vazbu.
Piece.SetEnabled(target, enabled)
- Strana: Klient / Server
- Deklarace:
Piece.SetEnabled(target: string, enabled: boolean) -> boolean - Popis: Zapne nebo vypne piece.
targetmůže být runtime ID world instance nebo prefab name.
Piece.SetCraftingStation(pieceTarget, stationTarget)
- Strana: Klient / Server
- Deklarace:
Piece.SetCraftingStation(pieceTarget: string, stationTarget: string) -> boolean - Popis: Připojí k
Piecepožadovanou crafting station. Typicky se používá na prefab, aby šlo vytvořit navazující výrobní zařízení odemykané jiným strojem.
Piece.SetResourceCost(pieceTarget, resources)
- Strana: Klient / Server
- Deklarace:
Piece.SetResourceCost(pieceTarget: string, resources: table) -> boolean - Popis: Přepíše build cost
Piecepřes stejné requirement tabulky jako uRecipe.Upsert.
CraftingStation.GetAll([prefabName])
- Strana: Klient / Server
- Deklarace:
CraftingStation.GetAll(prefabName?: string) -> table<string> - Popis: Vrátí runtime ID všech crafting station instancí ve scéně.
CraftingStation.GetData(runtimeId)
- Strana: Klient / Server
- Deklarace:
CraftingStation.GetData(runtimeId: string) -> table | nil - Popis: Vrátí informace o stanici: prefab, name, level, useDistance, linked piece prefab a position.
CraftingStation.SetLevel(target, level)
- Strana: Klient / Server
- Deklarace:
CraftingStation.SetLevel(target: string, level: number) -> boolean - Popis: Nastaví level stanice.
targetmůže být runtime ID nebo prefab name.
CraftingStation.SetUseDistance(target, distance)
- Strana: Klient / Server
- Deklarace:
CraftingStation.SetUseDistance(target: string, distance: number) -> boolean - Popis: Změní dosah používání stanice.
CraftingStation.SetName(target, name)
- Strana: Klient / Server
- Deklarace:
CraftingStation.SetName(target: string, name: string) -> boolean - Popis: Přepíše zobrazované interní jméno stanice.
Ukázka navazujícího chainu:
lua
Recipe.Upsert("IronSword", {
amount = 1,
craftingStation = "piece_forge",
minStationLevel = 2,
resources = {
{ item = "Iron", amount = 20 },
{ item = "Wood", amount = 2 }
}
})
Piece.SetCraftingStation("piece_artisanstation", "piece_forge")
Piece.SetResourceCost("piece_artisanstation", {
{ item = "Iron", amount = 10 },
{ item = "SurtlingCore", amount = 2 }
})Managed Animal API
Strana: pouze Server. Resource může vytvářet persistentní ochočená zvířata z existujících Valheim prefabů. Identifikátory mají formát zdo:userId:objectId; stabilní tag je unikátní v rámci resource a aktuálního světa. Nepoužívejte runtime instance ID jako uloženou identitu.
lua
local worldId = World.GetId() -- world UID jako řetězec, nikoliv název světa
local now = Time.Unix() -- UTC sekundy od Unix epoch
local player = Player.GetIdentity(peerId)
-- player = { id = platformIdentity, peerKey = exactPeerUidString,
-- name = playerName, position = { x, y, z } }
-- nil, pokud hráč nemá připravenou postavu / identitu
local id = Animal.Ensure('Boar', 'animal:42', x, y, z, 'Betty')
Animal.SetHome(id, x, y, z, 7)
Animal.Follow(id, peerId)
Animal.Rename(id, 'Betty II')
Animal.Heal(id)
local existingId = Animal.Find('animal:42') -- "" při neexistujícím tagu
local animal = Animal.Get(id) -- nil při neexistujícím objektu
Animal.Destroy(id) -- idempotentní při již odstraněném IDAnimal.Ensure(prefab, tag, x, y, z, name) -> string: vrátí existující resource-owned zvíře se stejným tagem nebo vytvoří nové. Prefab musí mítCharacter,BaseAIa platné síťovéZNetView.Animal.Get(id) -> table | nil:{ id, tag, name, position, health, loaded }. Funguje i nad nenačteným ZDO.healthje fyzické HP, ne procento.Animal.SetHome(id, x, y, z, [radius = 6]) -> true: nastaví domov a zruší následování; poloměr je 1–50 metrů.Animal.Follow(id, peerId) -> true: následuje připojenou postavu; nejde o změnu vlastníka. Resource musí sama ověřit oprávnění hráče a vzdálenost.Animal.Rename(id, name) -> true: zapíše replikované jméno, maximálně 64 znaků.Animal.Heal(id) -> true: vyléčí fyzické HP, ale neoživuje mrtvé. U načtené postavy použije herní heal RPC; u nenačtené obnoví uložené maximální HP.Animal.Destroy(id) -> true: odstraní načtené i nenačtené zvíře bez loot dropu.
Chybný vstup, cizí resource nebo neplatný svět vyvolají Lua chybu. Pouze Find/Get a idempotentní Destroy dovolují neexistující objekt. Tagy a vlastnictví přežijí resource restart i uložení světa. Tyto objekty se při stopnutí resource automaticky nemažou.
Managed AI je aktivní na aktuálním síťovém vlastníkovi, i když jde o klienta: zvířata se pasou v okolí domova, vracejí se do poloměru a mohou následovat hráče do 100m od domova. Vanilla množení, růst a loot jsou pro tato označená zvířata vypnuté; ekonomiku, biologický věk a produktové odměny zajišťuje resource. Klienti i server proto musí mít aktualizovaný engine.
Player.GetIdentity vrací stejnou vzdálenou platform identity jako permission systém. Listen-server host bez vzdáleného peeru má identitu local:<characterId>. Identitu ukládejte jako neprůhledný řetězec, ne jako číselné peer/server ID. World.GetId, Time.Unix a Player.GetIdentity jsou serverové API.
Universal UI okna otevřená přes UI.OpenWindow si nově pamatují resource, která je vytvořila, a při jejím stopnutí se zavřou a uvolní input capture.
Land API
Server spravuje autoritativní katalog, klient aplikuje pouze ochranné snapshoty. Pozemek je polygon v rovině XZ bez výškového omezení. Vrací tabulku { id, owner, name, type, price, forSale, points, members, access }; points = { { x, y, z }, ... }, members = { [identity] = level }. Prázdný katalog/členové mohou být v Lua JSON reprezentováni jako [].
Server
| Native | Kontrakt |
|---|---|
Land.Configure(consumerResource, [adminPermission]) | Určí vlastníka katalogu a závislou resource; výchozí permission je land.admin. |
Land.BeginUpdate() | Vrátí token exkluzivní aktualizace; odmítne souběh s rezervacemi rančů. |
Land.ValidateUpdate(token, catalogJson) | Ověří polygonovou geometrii, role, překryvy a ochranu používaných pozemků. |
Land.CommitUpdate(token, catalogJson) | Publikuje ověřený katalog a uvolní aktualizaci. Při chybě ponechá rezervace rančů zakázané do obnovy. |
Land.AbortUpdate(token) | Uvolní vlastní rozpracovanou aktualizaci. |
Land.Reserve(id, peerId, level) | Vrátí token rezervace práv úrovně 1-4; katalog se do uvolnění nesmí měnit. |
Land.Release(token) | Uvolní vlastní rezervaci; cizí nebo neplatný token vyvolá chybu. |
Land.SetUsage(ids) | Publikuje seznam používaných ID pozemků volající resource. |
Land.Measure(pointsJson) | Ověří polygon a vrátí plochu v m². |
Land.Get(id, [peerId = 0]) | Vrátí pozemek s právy daného hráče, jinak nil. |
Land.GetAt(peerId) | Vrátí pozemek pod aktuální serverově známou pozicí hráče, jinak nil. |
Land.ContainsDisc(id, x, y, z, radius) | Ověří celý kruh v polygonu, ne pouze jeho střed. |
Katalog je JSON objekt indexovaný ID. Engine přijímá 3-32 vrcholů, konečné souřadnice do ±20000, plochu 1-1000000 m² a odmítá dotyk/překryv pozemků. Resource může stanovit přísnější limity a musí sama řešit vlastnictví, cenu a SQL. aprts_landmark ověřuje kandidáta před SQL; po úspěšném SQL publikuje katalog. Po SQL chybě nebo předchozí chybě handleru vždy zavolá AbortUpdate. aprts_ranch drží Reserve až do dokončení svého MySQL zápisu. Neznámé nebo stále používané závislosti blokují smazání/změnu polygonu.
Client
| Native | Kontrakt |
|---|---|
Land.ExpectSnapshot() | Do prvního snapshotu odmítá chráněné interakce; listen server používá serverový katalog. |
Land.ApplyClientSnapshot(catalogJson, identity, admin, peersJson, adminsJson) | Aplikuje katalog, lokální práva a mapy vzdálených peerů pro kontrolu příchozích RPC. |
Land.GetLocal() | Vrátí aktuální pozemek s lokálními právy, jinak nil. |
Land.ShowBoundary([id]) | Zobrazí hranici pozemku; bez ID hranici skryje. |
peersJson je objekt { [exactPeerUidString] = identity }, adminsJson seznam přesných UID řetězců. Používejte Player.GetIdentity(peer).peerKey, nikoli tostring(peer) nad Lua double, které může ztratit přesnost velkého síťového UID. Snapshoty posílá pouze autoritativní server, ne nedůvěryhodný klient.
Úrovně přístupu jsou kumulativní: 1 dveře a péče o ranč, 2 kontejnery, 3 stavění/opravy/bourání, 4 plné užívání. Pouze skutečný vlastník/admin mění klíče a převody. Nativní ochrana zahrnuje stavby, hráčské poškození staveb, dveře, kontejnery a přijímaná interakční RPC. NPC/prostředí a původní wardy se nemění. Vyžaduje aktualizovaný engine na všech klientech; nejde o anti-cheat záruku. Při stopu katalogové resource zůstává poslední ochrana, nové rezervace jsou zakázané. Stop závislé resource uvolní její rezervace a zneplatní usage index.
Nativní výjimky se logují a převádějí na Lua chyby zachytitelné přes pcall. Json.Encode vynechává smazané/nil položky tabulek, místo aby z nich tvořil persistentní JSON null.