Luawe All pages

Names

Every thing in a level has a name. It is the first row in the editor's inspector, and it is how a script finds the thing. This page is about what a name is for, what can be done with one, and what keeps working when a name changes.

Every thing has a name

A thing is never without one. Whatever you add in the editor gets a name at once, from what it is: a piece of floor is Floor, a text is Text, a group is Group, and the others are Block, Decoration, Checkpoint, Button and so on. With Numbered names on (the editor's Esc menu), the next one is Floor2, then Floor3. You can type over any name.

A level made before this, or by hand, may have things with no name. When the level opens, the game and the editor give each of them a name by one rule, so a script sees the same names in both:

  • The name is the word for what the thing is, in English: Floor, Block, Text, Group.
  • If something already has that name, the thing gets the next free number: Floor2, Floor3. The number is never one that a node already goes by.
  • They are named in this order: floor first, then objects, then texts, then groups. Inside each, in the order the level has them.

So world.Floor2 is the same piece in the editor and in the game, whatever language the game is in. The word stays English; it is only a name.

The character and the camera have a name too, player.name and camera.name: "player" and "camera". They are always there, so player.exists and camera.exists are always true. None of these can be set.

Finding a thing by its name

local door = things.find("door") -- the first thing called door, or nil
local lamps = things.all("lamp") -- a list of every thing called lamp

print(door, #lamps)

things.find goes by the names things have right now. If nothing is called that, it gives nil.

A name can be changed

A script reads a thing's name as thing.name, and sets it the same way:

local door = things.find("door")
door.name = "open door"

print(things.find("door"))      -- nil: nothing is called door any more
print(things.find("open door")) -- the same door

It is the same thing with another name. Nothing else about it changes. A name is at most 200 bytes (a longer one is cut), and it may not have a letter in it that cannot be seen, such as a space with no width. Setting one like that stops the task and says so.

Two things can have the same name

Names do not have to be different. Two blocks can both be called spike, and a script can ask for all of them:

for _, spike in things.all("spike") do
    spike.alpha = 0.5
end

things.find("spike") gives the first one. If a script needs to tell two things apart, give them two names. A thing can also be told apart from another one with the same name by its place in the tree, or by a tag.

Copies keep the name

A copy made by a script has the same name and the same properties as the thing it was made from:

local coin = things.find("coin")
local copy = coin:clone()
print(copy.name)           -- coin
print(#things.all("coin")) -- one more than before

The editor does it differently, on purpose. When you add or copy a thing in the editor, it gets the next free name: Block, Block2, Block3. That is the Numbered names switch in the editor's Esc menu. With it off, a copy keeps the name it was copied from, as a script's copy does.

What a rename does not break

Changing a name must not break the level, so the game does not go by the name wherever the level's maker picked a thing in the editor:

  • A node whose Thing row is This thing only is about that one thing, whatever it is called now. (Everything called this goes by the name, and so is about every thing that has it.) A thing picked with the dropper is This thing only.
  • A thing picked in a marker's value, in a Path mask's list, or as the thing a Make node's child is made like, stays the thing that was picked.
  • A renamed thing keeps its nodes. It is the same thing, so what the level's nodes do to it, they go on doing.

What does go by the name is what a script types: things.find("door") asks for a name. If a script renames the door, the next things.find("door") does not find it. Keep what you found in a local and the name does not matter:

local door = things.find("door")
door.name = "open door"
door:tween({ y = door.y - 3 }, 1) -- door is the thing, not the word

Taking the nodes away from one thing

A thing's nodes work on it by default, and a script can switch that off with thing.nodes:

local coin = things.find("coin")
coin.nodes = false -- the nodes that pick coins up now leave this one alone
print(coin.nodes)  -- false

It is how a copy is made that is only there to be looked at. clone can do it in one go:

local coin = things.find("coin")
local icon = coin:clone({ nodes = false }) -- a coin that nothing picks up
icon.x = 2
icon.y = -4.2

The copy has the coin's name and picture, but no node reaches it. Setting icon.nodes = true gives them back.

Next: tags, a second way to say what a thing is.