update_properties

Updates the given properties in the entity if they are present already. How the method behaves when the property is not present depends on the add_if_missing flag.

Arguments

A table of Property instances, property Lua tables or property names to be removed.

Signature

---@param properties table[] @Array of properties to update
---@param add_if_missing boolean|nil @whether a missing property should be added if missing or not
function update_properties(properties, add_if_missing)

Example of Usage

-- bind the exposed entity UserData to a local variable
local entityAPI = alacrity.Entity

-- create a new random unique user ID
local id = alacrity.uuid.new_v4()

-- create a new Entity instance
local e = entityAPI.new({
    id = id,
    name = "Ad-Hoc Test Entity",
    description = "Ad-Hoc entity for testing",
    attributes = {},
    properties = {
        { name = "level", value = 10 },
        { name = "class", value = "warrior" },
    }
})

local ok, err = pcall(function()
    e:update_properties({
        { name = "level", value = 20 },
    })
end)
assert(ok and err == nil)

local level_property = e:get_property("level")
assert(level_property ~= nil)
assert(level_property.name == "level")
assert(level_property.value.Value == 20)

-- this call will idempotently do nothing
e:update_properties({
    { name = "house", value = "atreides" },
})
assert(entity.properties["house"] == nil)

local ok, err = pcall(function()
    e:update_properties({
        { name = "level", value = 30 },
        alacrity.Property.new("class", "mage"),
    })
end)
assert(ok and err == nil)

local level_property = e:get_property("level")
local class_property = e:get_property("class")

assert(level_property ~= nil)
assert(level_property.name == "level")
assert(level_property.value.Value == 30)

assert(class_property ~= nil)
assert(class_property.name == "class")
assert(class_property.value.Value == "mage")

-- this call will also add the missing "house" property to the entity 
local ok, err = pcall(function()
    e:update_properties({
        { name = "house", value = "harkonnen" },
    }, true)
end)

assert(ok and err == nil)

local house_property = e:get_property("house")

assert(house_property ~= nil)
assert(house_property.name == "house")
assert(house_property.value.Value == "harkonnen")