Detailed API reference

Generated from natives.md during 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é.
runtimeId ve tvaru instance:... nebo object:... 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
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á source peer ID odesílatele; u lokálního eventu je source = 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ý sourcePeer urč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 = true vyžaduje ACE command.<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. args je pole indexované od 1.

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.admin

ACE 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í nil a 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 *, command nebo command.* pokrývá také podřízené ACE jako command.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) -> string
GetConvarInt(key: string, defaultValue: number) -> number
GetConvarFloat(key: string, defaultValue: number) -> number
GetConvarBool(key: string, defaultValue: boolean) -> boolean
SetConvar(key: string, value: string) -> void
SetReplicatedConvar(key: string, value: string) -> void

Convars aktuální resource

GetResourceConvar(key: string, defaultValue: string) -> string
GetResourceConvarInt(key: string, defaultValue: number) -> number
GetResourceConvarFloat(key: string, defaultValue: number) -> number
GetResourceConvarBool(key: string, defaultValue: boolean) -> boolean
SetResourceConvar(key: string, value: string) -> void
SetReplicatedResourceConvar(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 '...' a manifest_version '...',
client_script 'client.lua' nebo client_scripts { 'a.lua', 'b.lua' },
server_script 'server.lua' nebo server_scripts { 'a.lua', 'b.lua' },
file 'data/file.json' nebo files { 'data/a.json', 'assets/icon.png' },
asset_bundle 'assets/content.bundle' nebo asset_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.

query vrací pole řádků,
single vrací první řádek nebo nil,
scalar vrací první hodnotu nebo nil,
insert vrací last insert ID,
update vrací 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]) -> operationId
MySQL.query.await(sqlOrStoreId, [params]) -> table<table>
MySQL.single(sqlOrStoreId, [params], [callback]) -> operationId
MySQL.single.await(sqlOrStoreId, [params]) -> table | nil
MySQL.scalar(sqlOrStoreId, [params], [callback]) -> operationId
MySQL.scalar.await(sqlOrStoreId, [params]) -> any | nil
MySQL.insert(sqlOrStoreId, [params], [callback]) -> operationId
MySQL.insert.await(sqlOrStoreId, [params]) -> number | string
MySQL.update(sqlOrStoreId, [params], [callback]) -> operationId
MySQL.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]) -> operationId
MySQL.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]) -> operationId
MySQL.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]) -> operationId
MySQL.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)) -> any
MySQL.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() -> boolean
MySQL.awaitConnection() -> true
MySQL.ready(callback) -> void
MySQL.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 0 pro lokálního hráče. Starší peerId pojmenová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í serverId používej přes selektor tabulku nebo string server: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 tvaru server:12 nebo peer:-1471880800, i tabulku se serverId nebo starším peerId.

[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 je notify(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 peerId vš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 serverId vš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, jinak false. Pokud je zadaná expectedRevision, operace selže bez změny při nesouladu revize. Na dedicated je pro vlastněný inventář vzdáleného hráče aktuálně potřeba klientské workflow s peerId = 0.

`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 podporuje itemId, prefab, itemType, nameContains, equipped, x, y, minCount, maxCount, quality, qualityMin a qualityMax.

`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, worldLevel a customData.

`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 expectedRevision vrátí nil bez 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 expectedRevision selž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 rovnou expectedRevision a 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ři BeginTransaction.

`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 lze pro vlastněný hráčský inventář použít klientské workflow s peerId = 0.

`Inventory.CommitTransaction(transactionId, [expectedRevision])`

Strana: Klient / Server
Deklarace: Inventory.CommitTransaction(transactionId: number, expectedRevision?: number) -> boolean
Popis: Ukončí aktivní transaction a uvolní lock. Volitelná expectedRevision umožň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. prefabName filtruje například piece_chest_wood; kind přijímá any, vanilla nebo resource. Výchozí any zahrnuje 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, nebo nil.

`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, isInUse a position.

`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. Vzdálený inventář není na dedicated serveru kompletně replikovaný, proto klientská workflow používají pro lokálního hráče peerId = 0 a data následně předají serverovému Lua eventu.

`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 = true cílový slot obsazený, operace selže. Pro vzdáleného hráče na dedicated serveru má manipulaci provést jeho klient s peerId = 0.

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)
end

JSON 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
Json.Decode

`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..N serializuje 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
Storage.WriteJson
Storage.Delete

`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
UI.HidePanel

`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. definition podporuje klíče title, subtitle, accent, width, anchor (left, center nebo right) a rows. Řádek s číselným progress v rozsahu 0..1 vykreslí pod textem progress bar; opakované volání se stejným panelId panel 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.

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

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

craftingStation a repairStation očekávají prefab name objektu se CraftingStation komponentou.
resources je povinné pole ingrediencí; lze použít klíč item nebo prefab.

`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 GameObject instancí, 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í localScale world instance.

`Asset.SetScale(runtimeId, x, [y], [z])`

Strana: Klient / Server
Deklarace: Asset.SetScale(runtimeId: string, x: number, y?: number, z?: number) -> boolean
Popis: Nastaví localScale objektu. Při zadání jen x se 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))
end

`AssetBundle.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 GameObject prefab.

`AssetBundle.RegisterNetworkPrefab(relativePath, assetName, [persistent])`

Strana: Klient / Server
Deklarace: AssetBundle.RegisterNetworkPrefab(relativePath: string, assetName: string, persistent?: boolean) -> boolean
Popis: Načte GameObject z bundle a zaregistruje ho pod jeho prefab názvem do síťové scény. Prefab musí mít ZNetView na kořenovém objektu. persistent je ve výchozím stavu true.
Lifecycle: Preferujte deklaraci network_prefab v manifestu; engine ji provede na serveru i klientu před jejich skripty. Při zastavení resource engine odstraní její prefaby ze ZNetScene a itemy z ObjectDB; 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')
end

`World.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 ItemDrop a ZNetView do ObjectDB i ZNetScene. Díky tomu lze item používat v inventáři, receptech a jako síťový world drop.
Lifecycle: Preferujte deklaraci bundle_item v manifestu; engine ji provede na obou stranách. Při zastavení resource se item odstraní z ObjectDB i ZNetScene, 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_item v 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, description
icons = { { file = "assets/icon.png" }, ... } pro PNG přímo v resource
icons = { { bundle = "cesta", asset = "assetName" }, ... } pro Sprite z AssetBundle
damage a damagePerLevel: generic, blunt, slash, pierce, chop, pickaxe, fire, frost, lightning, poison, spirit
maxDurability, durabilityPerLevel, blockPower, blockPowerPerLevel
deflectionForce, deflectionForcePerLevel, timedBlockBonus, attackForce
attackStaminaModifier, 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 Character a ZNetView. Klon zachová model, skeleton, animace, AI a útoky základního moba.
Lifecycle: Preferujte derived_mob nebo derived_mobs v manifestu. Klonované materiály, PNG textura a prefab se odstraní při zastavení resource.

Podporované klíče definition:

name, health, faction
walkSpeed, speed, runSpeed, turnSpeed
fleeIfLowHealth, viewRange, hearRange
tolerateWater, tolerateFire, tolerateSmoke, tolerateTar
texture = { 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 GameObject z bundle a vytvoří jeho world instanci. Vrací runtime ID object:....

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))
end

Machine & 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 Piece a 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 Piece instancí, 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. target můž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 Piece pož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 Piece přes stejné requirement tabulky jako u Recipe.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. target můž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 }
})

Detailed API reference ​

Stav API ​

Přehled jmenných prostorů (Namespaces) ​

Runtime a scheduler ​

CreateThread(callback) ​

Wait(milliseconds) ​

SetTimeout(milliseconds, callback) ​

ClearTimeout(taskId) ​

SetInterval(milliseconds, callback) ​

ClearInterval(taskId) ​

Schedule(expression, callback) ​

Eventy a síťová komunikace ​

AddEventHandler(eventName, callback) ​

RegisterNetEvent(eventName, callback) ​

TriggerEvent(eventName, ...) ​

TriggerServerEvent(eventName, ...) ​

TriggerClientEvent(eventName, targetPeer, ...) ​

Command.Execute(rawCommand, [sourcePeer]) ​

Commands, exports a permissions ​

RegisterCommand(commandName, callback, [restricted]) ​

exports(name, callback) ​

exports[resourceName][exportName](...) ​

HasPermission(permission) ​

Player.HasPermission(peerId, permission) ​

IsPlayerAceAllowed(source, ace) ​

IsPlayerAdmin() ​

GetCurrentResourceName() ​

Convar API ​

Globální convars ​

Convars aktuální resource ​

Resource manifest ​

MySQL API ​

Konfigurace ​

Parametry a výsledky ​

Základní operace ​

MySQL.prepare ​

MySQL.rawExecute ​

MySQL.store(sql) ​

MySQL.transaction ​

MySQL.startTransaction ​

Readiness ​

1. Player API ​

[x] Player.GetPos(serverId) ​

[x] Player.SetPos(serverId, x, y, z) ​

[x] Player.GetHealth(serverId) ​

[x] Player.SetHealth(serverId, amount) ​

[x] Player.GetStamina(serverId) ​

[x] Player.SetStamina(serverId, amount) ​

[x] Player.GetName(serverId) ​

[x] Player.GetSteamId(serverId) ​

[x] Player.GetServerId(playerSelector) ​

[x] Player.Notify(...) ​

[x] Player.PlayEffect(...) ​

[x] Player.GetAll() ​

[x] Player.GetAllServerIds() ​

2. Inventory API ​

Inventory.GetItemCount(peerId, prefabName) ​

Inventory.HasItem(peerId, prefabName, amount) ​

Inventory.AddItem(peerId, prefabName, amount, [quality]) ​

Inventory.RemoveItem(peerId, prefabName, amount) ​

Inventory.GetEmptySlots(peerId) ​

Inventory.GetAllItems(peerId) ​

Inventory.GetItem(peerId, itemId) ​

Inventory.GetItemAt(peerId, x, y) ​

Inventory.FindItems(peerId, [filter]) ​

Inventory.GetSize(peerId) ​

Inventory.MoveItem(peerId, itemId, targetX, targetY) ​

Inventory.RemoveItemById(peerId, itemId, [amount]) ​

Inventory.UpdateItem(peerId, itemId, patch) ​

Inventory.SplitStack(peerId, itemId, amount) ​

Inventory.MergeStacks(peerId, sourceItemId, targetItemId) ​

Inventory.Resize(peerId, width, height, [overflowPolicy]) ​

Inventory.GetRevision(peerId) ​

Inventory.BeginTransaction(peerId, [expectedRevision]) ​

Inventory.CommitTransaction(transactionId, [expectedRevision]) ​

Inventory.RollbackTransaction(transactionId) ​

Container API ​

Container.SpawnForPlayer(peerId, prefabName, [distance], [width], [height], [tag]) ​

Container.GetAll([tag]) ​

Container.FindNearby(x, y, z, radius, [prefabName], [kind]) ​

Detailed API reference

Stav API

Přehled jmenných prostorů (Namespaces)

Runtime a scheduler

`CreateThread(callback)`

`Wait(milliseconds)`

`SetTimeout(milliseconds, callback)`

`ClearTimeout(taskId)`

`SetInterval(milliseconds, callback)`

`ClearInterval(taskId)`

`Schedule(expression, callback)`

Eventy a síťová komunikace

`AddEventHandler(eventName, callback)`

`RegisterNetEvent(eventName, callback)`

`TriggerEvent(eventName, ...)`

`TriggerServerEvent(eventName, ...)`

`TriggerClientEvent(eventName, targetPeer, ...)`

`Command.Execute(rawCommand, [sourcePeer])`

Commands, exports a permissions

`RegisterCommand(commandName, callback, [restricted])`

`exports(name, callback)`

`exports[resourceName][exportName](...)`

`HasPermission(permission)`

`Player.HasPermission(peerId, permission)`

`IsPlayerAceAllowed(source, ace)`

`IsPlayerAdmin()`

`GetCurrentResourceName()`

Convar API

Globální convars

Convars aktuální resource

Resource manifest

MySQL API

Konfigurace

Parametry a výsledky

Základní operace

`MySQL.prepare`

`MySQL.rawExecute`

`MySQL.store(sql)`

`MySQL.transaction`

`MySQL.startTransaction`

Readiness

1. Player API

[x] `Player.GetPos(serverId)`

[x] `Player.SetPos(serverId, x, y, z)`

[x] `Player.GetHealth(serverId)`

[x] `Player.SetHealth(serverId, amount)`

[x] `Player.GetStamina(serverId)`

[x] `Player.SetStamina(serverId, amount)`

[x] `Player.GetName(serverId)`

[x] `Player.GetSteamId(serverId)`

[x] `Player.GetServerId(playerSelector)`

[x] `Player.Notify(...)`

[x] `Player.PlayEffect(...)`

[x] `Player.GetAll()`

[x] `Player.GetAllServerIds()`

2. Inventory API

`Inventory.GetItemCount(peerId, prefabName)`

`Inventory.HasItem(peerId, prefabName, amount)`

`Inventory.AddItem(peerId, prefabName, amount, [quality])`

`Inventory.RemoveItem(peerId, prefabName, amount)`

`Inventory.GetEmptySlots(peerId)`

`Inventory.GetAllItems(peerId)`

`Inventory.GetItem(peerId, itemId)`

`Inventory.GetItemAt(peerId, x, y)`

`Inventory.FindItems(peerId, [filter])`

`Inventory.GetSize(peerId)`

`Inventory.MoveItem(peerId, itemId, targetX, targetY)`

`Inventory.RemoveItemById(peerId, itemId, [amount])`

`Inventory.UpdateItem(peerId, itemId, patch)`

`Inventory.SplitStack(peerId, itemId, amount)`

`Inventory.MergeStacks(peerId, sourceItemId, targetItemId)`

`Inventory.Resize(peerId, width, height, [overflowPolicy])`

`Inventory.GetRevision(peerId)`

`Inventory.BeginTransaction(peerId, [expectedRevision])`

`Inventory.CommitTransaction(transactionId, [expectedRevision])`

`Inventory.RollbackTransaction(transactionId)`

Container API

`Container.SpawnForPlayer(peerId, prefabName, [distance], [width], [height], [tag])`

`Container.GetAll([tag])`

`Container.FindNearby(x, y, z, radius, [prefabName], [kind])`