Engine.tag

Tags of the loaded map. Every function raises an error when no map is loaded.

Tag groups are written as strings, such as "weapon", "biped" or "scenario_structure_bsp". See TagGroup in the types for the full list.

Tag data is a live view into the map: changing a field changes the game right away, and the change lasts until the map is loaded again. Tag blocks are arrays indexed from 1, and # gives their number of elements.

Functions

Engine.tag.lookupTag

local handle = Engine.tag.lookupTag(path, group)

Returns the handle of the tag with that path and group, or nil when there is none. Paths use backslashes and have no extension, such as "weapons\\pistol\\pistol".

Engine.tag.getTagData

local data = Engine.tag.getTagData(handle, group)

Returns the data of a tag. Its type depends on the group: a Weapon for "weapon", a Biped for "biped", and so on. Raises an error when the tag is not of that group.

Engine.tag.getTagEntry

local entry = Engine.tag.getTagEntry(handle)

Returns the TagEntry of a tag, with its path, group and handle, or nil when the handle is not valid. entry:getData() returns its data, like getTagData.

Engine.tag.filterTags

local entries = Engine.tag.filterTags(group, pathFilter)

Returns the TagEntry of every tag of a group. With pathFilter, only tags whose path contains that text are returned.

Engine.tag.importTag

local handle = Engine.tag.importTag(mapName, tagPath, group)

Copies a tag and everything it references from another map into the loaded one, and returns its handle in the loaded map. The copy does not depend on the other map. When the loaded map already has a tag with that path and group, that tag is returned instead of importing it again, but the source map and its tag must still exist. Returns nil when the map or the tag cannot be found or imported.

mapName is the name of the map without extension, such as "bloodgulch".

Example

-- Double the magazine size of every weapon.
for _, entry in ipairs(Engine.tag.filterTags("weapon")) do
    local weapon = entry:getData()
    for i = 1, #weapon.magazines do
        local magazine = weapon.magazines[i]
        magazine.roundsLoadedMaximum = magazine.roundsLoadedMaximum * 2
    end
end