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.

Managed livestock ​

Server. Animal.* manages persistent, resource-owned vanilla animals by stable tag, with native AI running on the current network owner:

lua
local player = Player.GetIdentity(peerId)
if player then
  local p = player.position
  local id = Animal.Ensure('Boar', 'pet:42', p.x + 2, p.y, p.z, 'Betty')
  Animal.SetHome(id, p.x, p.y, p.z, 7)
  Animal.Follow(id, peerId)
end

Animal.Find, Animal.Get, Animal.Rename, Animal.Heal and Animal.Destroy complete the lifecycle. Access is resource-scoped; invalid inputs and cross-resource access throw errors. The calling resource must authorize the player.

Managed animals do not use vanilla reproduction, growth or loot. They survive resource stop and world saves; both clients and server need the updated engine. World.GetId() returns the world UID as a string; Time.Unix() returns UTC seconds.

See the ranch example and full API contracts.

Land ownership and protection ​

Server authority / client protection snapshots. aprts_landmark maintains the persistent catalog; Land.Get(id, peer) and Land.GetAt(peer) return a plot including its effective access level. Land.ContainsDisc(id, x, y, z, radius) checks that an entire circular pen fits inside its XZ polygon.

Use Land.Reserve(id, peer, level) before asynchronous ranch writes and Land.Release(token) on every completion/error path. Catalog updates use Land.BeginUpdate, ValidateUpdate, CommitUpdate and AbortUpdate. Land.SetUsage(ids) prevents deleting/reshaping plots still used by a resource. Do not perform cyclic synchronous exports between land and ranch resources.

Levels are cumulative: 1 doors/care, 2 containers, 3 building/repair/demolition, 4 full land use. Only owners/admins change keys or ownership. Native hooks include player structure damage and owner-side interaction RPCs, but do not bypass wards or provide an anti-cheat guarantee against modified clients.

See landmark setup and full Land API contracts.

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.