Luawe All pages

The world, the level and things inside things

A script has three big names to start from:

NameWhat it is
worldEverything in the level's space: all its things, and the questions you can ask about them. It is the top of the Explorer
levelWhat the level says about itself: its name, its song, how long it is. It can be read, never changed. It also ends the run
playerThe character. Things, the character and the camera has it

This page is about world and level, and about putting things inside other things.

Reaching a thing through the world

You know things.find("door"). A thing can also be reached the way the Explorer shows it: start at world and say its name after a dot.

local door = world.Door
door.alpha = 0.5

local block = world["My block"] -- a name with a space needs brackets

world.Door is the first thing at the top of the level called Door. When nothing is, it is nil, as things.find is. A name that world has a word of its own for (raycast, name) gives that word. To get a thing with such a name, ask world:find("name").

Things inside things

In the editor's Explorer, drag a thing onto another thing and it goes inside it, as a file goes in a folder. Any thing can be put inside any thing: a block in a block, a text in a floor.

Being inside does not make a group. A thing inside another is still drawn, moved, touched and keyed on its own. What changes is where it stands in the Explorer, and how a script reaches it: after a dot.

-- a crate with two apples in it, and a seed in the first apple
local crate = things.new(cat.Kind.decoration, { centerX = 2, centerY = 2, width = 2, height = 2, name = "Crate" })
local apple = things.new(cat.Kind.decoration, { centerX = 2, centerY = 2, width = 0.5, height = 0.5, name = "Apple" })
local seed = things.new(cat.Kind.decoration, { centerX = 2, centerY = 2, width = 0.2, height = 0.2, name = "Seed" })

apple.holder = crate -- one way: put the apple inside the crate afterwards
seed.holder = apple

-- the other way: make the second apple inside the crate, with the third value
things.new(cat.Kind.decoration, { centerX = 3, centerY = 2, width = 0.5, height = 0.5, name = "Apple2" }, crate)

print(world.Crate.Apple.Seed.path)
print(world.Crate.Apple2.path)

It prints:

It prints

world.Crate.Apple.Seed
world.Crate.Apple2

Both ways end the same. With the third value (or holder = crate among the properties) the thing is made inside the crate, and the events about it are heard once. Giving a holder both ways in one call stops the script and says so.

Two things inside one thing can have the same name. A dot gives the first one put there.

holder is what a thing is in. It reads as a thing, or world for a thing at the top, and setting it puts the thing somewhere else, with everything that is inside it. A thing cannot be put inside itself, or inside something that is in it.

path is where the thing is, as text, for showing. A thing that has gone has no holder and no path: they are nil.

Asking what is inside

These work on any thing, and on world:

WrittenGives
crate:inside()A list of what is directly inside it, in the Explorer's order
crate:allInside()A list of everything inside it, deep down, each thing before what is in it
crate:find("Seed", true)The first thing inside it with that name, or nil. Without true it looks only at what is directly inside
seed:findHolder("Crate")The nearest thing it is inside that matches, or nil
crate:holds(seed)Is the seed somewhere inside the crate?
seed:isIn(crate)The same, asked the other way round
crate:waitFor("Apple", 5)The thing directly inside with that name. If there is none yet, it waits until one is put there, or until the seconds are up (then nil)
crate:clearInside()Destroys everything inside it. The crate stays

With the crate and its apples from above:

local crate = world.Crate
local seed = crate:find("Seed", true)
local second = crate:inside()[2]

print(#crate:inside(), #crate:allInside())                   -- 2 3
print(crate:find("Seed"), crate:find("Seed", true).name)     -- nil Seed
print(crate:holds(seed), seed:isIn(crate), seed:isIn(second)) -- true true false

Searches

Where a function above says "that matches", it takes a search: a name, or a table that says more. A table can have a name, a kind and a tag, and a thing has to fit all it has.

local crate = world.Crate
local fruit = crate:inside({ tag = "Fruit" })
local texts = world:allInside({ kind = cat.Kind.text })
local both = world:allInside({ kind = cat.Kind.decoration, name = "Apple" })

The kinds are cat.Kind.object, cat.Kind.block, cat.Kind.decoration, cat.Kind.floor, cat.Kind.text, cat.Kind.group and cat.Kind.any. A search with nothing in it stops the script and says that a search needs a name, a kind or a tag.

Taking things along

Putting a thing in a thing moves it with everything inside it. So do two more:

  • crate:clone() makes a copy of the crate and of everything inside it, each copy inside the copy of what its original is in. A group inside a thing cannot be copied, and then nothing is. Names says how a copy's nodes are handled.
  • crate:destroy() destroys the crate and everything inside it, the deepest first.
local crate = world.Crate
local seed = crate:find("Seed", true)

local copy = crate:clone()
print(#copy:allInside(), copy.holder == world) -- 3 true

crate:destroy()
wait()
print(seed.exists, copy.exists) -- false true: the seed went with the crate

How far down a tree goes: a thing can be inside up to 32 things, and a script can move up to 20,000 of the level's own things from their place in the editor's tree. Past that, the script stops with a message. The tree has no loops either.

Hearing what comes and goes

Things inside things have events, the same on a thing and on world:

EventHappens whenGives
thingAddedA thing is put directly inside it, or made thereThe thing
thingRemovedA thing directly inside it leaves, or goes for goodThe thing
addedInsideA thing is put anywhere inside it, deep down tooThe thing
removingInsideJust before a thing leaves from anywhere inside itThe thing, which can still be read
holderChangedIt moves, or a thing it is inside of movesThe thing that moved, and what it is in now
local crate = world.Crate

crate.thingAdded:connect(function(thing)
    print(thing.name .. " went in")
end)

crate.thingRemoved:connect(function(thing)
    print(thing.name .. " came out")
    if #crate:inside() == 0 then
        print("the crate is empty")
    end
end)

A move from one place to another is heard as removingInside where the thing was, and then addedInside where it ends up. A thing that is destroyed takes what is inside it along. For each thing the events are heard, then its own removing event, deepest first, and then everything that was listening to it stops.

What world has of its own

world answers everything a thing does about the tree, as a thing at the very top. Its own answers are plain:

WrittenIs
world.name"world"
world.path"world": where every path starts
world.holderAlways nil: the world is inside nothing
world.existsAlways true
world.thingAdded, world.thingRemovedA thing is put at the top, or leaves it
world.addedInside, world.removingInsideA thing is made, moved or destroyed anywhere in the level
world.holderChangedNever happens: the world never moves

So a script can listen to the whole level at once. This one hears every thing that is made or moved, wherever it goes:

world.addedInside:connect(function(thing)
    print(thing.name .. " is in the level at " .. thing.path)
end)

The world cannot be destroyed or copied: world:clearInside() is the way to empty the level.

The level

level is the other side. world is what is inside the level's space. level is what stands outside it: the facts about the level, and the things that end a try.

print(level.name, level.author)         -- the level's name, and who made it
print(level.description)                -- what its maker wrote
print(level.difficulty)                 -- 1 to 10
print(level.song, level.artist)         -- the song's name, and who made that
print(level.bpm, level.length)          -- beats a minute, and how many beats long
print(level.startX, level.startY)       -- where the character starts, in tiles

All of these can be read and none can be set. level.name = "Mine" stops the script and says that a level's values can only be read. The same goes for the functions: level.win = nil is refused.

What level can do:

level.checkpoint() -- a try that fails starts again from here
level.win()        -- the level is completed
level.fail()       -- the run fails, like player:kill()
level.onBeat(16, function() print("beat sixteen") end)

and its events, which fire as the song plays: level.step (48 times a beat), level.beat and level.frame. Events has them.

Looking round the world

What a straight line meets first, what is near a place, what lies in a circle or in a box: all of these are questions about the things in the level's space, so they are asked of world:

local hit = world:raycast(0, 0, 10, 0)
local near = world:nearest(player.x, player.y, { kind = cat.Kind.hazard, within = 4 })
local close = world:thingsInCircle(player.x, player.y, 3)
local inside = world:thingsInBox(10, 4, 6, 2)
local onDoor = world:thingsIn(world.Door)

Each can look for one kind only: kind = cat.Kind.hazard is what kills, kind = cat.Kind.solid is the walls (blocks the character can't go through). Raycasting is a page of its own about these.

Next: markers.