Luawe All pages

Tags

A name says which thing something is. A tag says what kind of thing it is. A tag is a short word, such as Coin or Enemy, and a thing can carry as many as sixteen. Many things can carry the same one.

Tags are made for rules like "everything with the tag Coin is picked up when the character touches it". The script writes the rule once. A thing becomes a coin by getting the tag, and stops being one when the tag comes off.

Giving a thing tags

In the editor, a thing's rows have a Tags row: type a word and add it. A script does the same with thing:addTag, and takes one off with thing:removeTag:

local door = things.find("door")

door:addTag("Locked")
print(door:hasTag("Locked")) -- true

door:removeTag("Locked")
print(door:hasTag("Locked")) -- false

thing.tags is the list of what a thing has, in the order it got them:

local door = things.find("door")
door:addTag("Wood")
door:addTag("Big")

for _, tag in door.tags do
    print(tag)
end

Giving a tag a thing already has, or taking off one it does not have, does nothing.

Finding every thing with a tag

things.tagged gives a list of everything that has the tag right now:

for _, coin in things.tagged("Coin") do
    coin.alpha = 0.5
end
print(#things.tagged("Coin") .. " coins")

The list is in no set order. A tag that nothing has gives an empty list.

Doing something when a tag is given or taken off

Looking at the things that have a tag once is not enough for a rule that goes on. A thing may get the tag later, and one may lose it. Two events tell a script:

  • things.tagAdded("Coin") happens when a thing gets the tag.
  • things.tagRemoved("Coin") happens when a thing loses it.

Both are given the thing. The events are made for one tag, so the tag goes in brackets before :connect:

things.tagAdded("Burning"):connect(function(thing)
    thing:tween({ alpha = 0.4 }, 0.3)
end)

things.tagRemoved("Burning"):connect(function(thing)
    thing:tween({ alpha = 1 }, 0.3)
end)

What a thing has when the level starts does not set off tagAdded: nothing was given. A rule has to start with the things that have the tag already, and then listen for the ones that get it. That is two lines, and it is the whole of the next example.

Coins by tag

Everything that has the tag Coin is picked up when the character touches it. The script gives each coin a maid that keeps what the coin listens to, so that it can stop listening when the tag comes off. Paste it into a script and test play it (F5): it makes a path with five squares on it, and gives each the tag.

const TAG = "Coin"

-- The count, pinned to the top left corner of the screen.
local count = 0
local label = things.new(cat.Kind.text, { x = -8.4, y = -4.4, text = "Coins: 0", pinned = true, align = cat.Align.left })

-- Each coin gets a maid: it keeps what the coin listens to, and cleans it all up in one go.
local maids = {}

-- A thing gets the tag: it starts to act like a coin.
local function becomeCoin(coin)
    local coinMaid = maid.new()
    coinMaid:give(coin.touched:connect(function()
        count += 1
        label.text = `Coins: {count}`
        sound.play("@coin")
        coin:destroy() -- it goes, and its tag goes with it
    end))
    maids[coin] = coinMaid
end

-- A thing loses the tag, or goes: its maid cleans up, and it stops acting like a coin.
local function stopBeingCoin(coin)
    if maids[coin] then
        maids[coin]:clean()
        maids[coin] = nil
    end
end

-- Everything that has the tag already, and everything that gets it from now on.
for _, coin in things.tagged(TAG) do
    becomeCoin(coin)
end
things.tagAdded(TAG):connect(becomeCoin)
things.tagRemoved(TAG):connect(stopBeingCoin)

-- Something to try it on: a path with five yellow squares on it, each given the tag.
local x, y = camera.x, camera.y
things.new(cat.Kind.floor, { centerX = x + 5, centerY = y, width = 14, height = 3 })
for i = 1, 5 do
    local square = things.new(cat.Kind.decoration, { centerX = x + i * 2, centerY = y, width = 0.8, height = 0.8, color = color.rgb(255, 214, 92) })
    square:addTag(TAG)
end

What to notice:

  • The rule is in becomeCoin and stopBeingCoin. Nothing else knows what a coin is. To make a coin, give a thing the tag, in the editor or from a script: thing:addTag("Coin").
  • maids[coin] is the maid that holds the connection connect gave back. clean() takes it off, so a coin that loses its tag is not picked up any more.
  • Copies are covered: a copy of a thing has the tags its original has at that moment, so it is a coin too, and things.tagAdded is heard for it.
  • The same example is in the editor, under Try an example, as Coins by tag.

Try: give a coin a second tag, Gold, and let a gold coin count as 5. Take the tag off one coin after three seconds with task.delay(3, function() coin:removeTag("Coin") end), and see that the character can walk through it.

When a thing goes

A thing that is destroyed, or whose time is up, takes its tags off as it goes, so things.tagRemoved is heard for each. Then its own event, thing.removing, happens once, and everything that was listening to the thing stops by itself.

local coin = things.find("coin")

coin.removing:connect(function(gone)
    print(gone.name .. " is going")  -- it can still be read here, but not changed
end)

That is why a rule like the coins above does not leak: a coin that is picked up and destroyed lets go of its touched listener without the script doing anything. stopBeingCoin is only needed for a coin that stays and loses its tag.

The rules

A tag isA word of up to 64 bytes, with no letter in it that cannot be seen. A number is kept as its text: addTag(2) gives "2"
MatchingExact. "Coin" is not "coin"
A thing hasUp to 16 tags, each once
A level hasUp to 256 different tags written in it. A run can use up to 1024 in all
Where they are keptThe ones set in the editor are saved with the level. What a script gives or takes is for the run only: a new try starts again, and a checkpoint keeps it as it was
A copyHas the tags its original has at that moment
What has themFloor, objects, texts, groups and the things a script makes

The Logic tab's nodes do not use tags. They are for scripts.

Next: attributes, values a thing keeps for itself.