The world, the level and things inside things
A script has three big names to start from:
| Name | What it is |
|---|---|
world | Everything in the level's space: all its things, and the questions you can ask about them. It is the top of the Explorer |
level | What the level says about itself: its name, its song, how long it is. It can be read, never changed. It also ends the run |
player | The 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 bracketsworld.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.Apple2Both 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:
| Written | Gives |
|---|---|
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 falseSearches
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 crateHow 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:
| Event | Happens when | Gives |
|---|---|---|
thingAdded | A thing is put directly inside it, or made there | The thing |
thingRemoved | A thing directly inside it leaves, or goes for good | The thing |
addedInside | A thing is put anywhere inside it, deep down too | The thing |
removingInside | Just before a thing leaves from anywhere inside it | The thing, which can still be read |
holderChanged | It moves, or a thing it is inside of moves | The 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:
| Written | Is |
|---|---|
world.name | "world" |
world.path | "world": where every path starts |
world.holder | Always nil: the world is inside nothing |
world.exists | Always true |
world.thingAdded, world.thingRemoved | A thing is put at the top, or leaves it |
world.addedInside, world.removingInside | A thing is made, moved or destroyed anywhere in the level |
world.holderChanged | Never 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 tilesAll 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.