Skip to content

Gameplay and World

Players

Common player calls:

lua
Player.GetAll()
Player.GetName(peerId)
Player.GetSteamId(peerId)
Player.GetPos(peerId)
Player.GetHealth(peerId)
Player.Notify(peerId, message, kind)
Player.PlayEffect(peerId, prefabName)

Position, health, stamina, inventory, and permission decisions must be authoritative on the server.

Containers and equipment

Server mutations; client/server discovery

lua
local nearby = Container.FindNearby(x, y, z, 20, nil, 'vanilla')
local items = Container.GetAllItems(containerId)

Container.TransferFromPlayer(containerId, peerId, itemId, amount)
Container.TransferToPlayer(containerId, peerId, itemId, amount)

Container state is persisted by world-scoped ID. The server can discover and mutate enrolled unloaded containers without a live Unity object.

Equipment APIs expose equipped slots and stateless take/give operations for Lua-owned gear systems:

lua
local equipped = Equipment.GetEquipped(peerId)
local item = Equipment.TakeEquipped(peerId, 'helmet')
Equipment.GiveItem(peerId, item, true)

UI

Client

lua
UI.ShowPanel('status', {
  title = 'Server status',
  rows = {
    { label = 'Event', value = 'Active' },
    { label = 'Players', value = '12' }
  }
})

UI.HidePanel('status')

The lightweight panel API is intended for status and utility interfaces. A browser-based NUI runtime is not part of the current release.

Assets, items, recipes, and mobs

Resources can declare custom content in manifest.lua or register it through runtime APIs:

lua
Asset.HasPrefab(prefabName)
AssetBundle.Load(relativePath)
AssetBundle.RegisterNetworkPrefab(relativePath, assetName, persistent)
AssetBundle.RegisterItem(relativePath, assetName, persistent)
Item.RegisterDerived(basePrefab, prefabName, definition, persistent)
Mob.RegisterDerived(basePrefab, prefabName, definition, persistent)
Recipe.Upsert(itemPrefab, definition)
World.SpawnNetworked(prefabName, x, y, z, rotationY)
World.DestroyNetworked(zdoId)

Use persistent registration for content referenced by world saves or inventories. The gold_mining example demonstrates the full registration path.

Zones

Client / Server; server-owned for authoritative gameplay

lua
Zone.CreateCircle('arena', x, y, z, 30)

AddEventHandler('zone:onEnter', function(zoneName, peerId)
  if zoneName == 'arena' then
    Player.Notify(peerId, 'Arena entered', 'TopLeft')
  end
end)

Circle and polygon zones emit enter and exit events and are removed automatically when their owning resource stops.

Lua resources for Valheim, built on a server-authoritative runtime.